HP 3000 Manuals HP 3000 Manuals
NSINFO Intrinsic This intrinsic is used to programmatically obtain information about NS environments that have been created in your session. These are environments created by either a DSLINE envID, or a REMOTE HELLO...;DSLINE= envID command. This intrinsic also allows you to obtain some information about your local node (such as the local node name). Syntax _____________________________________________________________________________ | | | BA I | | NSINFO ( [envID], [envIDlength], | | | | I I | | [envnum] status | | (IV) (BA) | | [,itemnum1, item1] | | [,itemnum2, item2] | | [,itemnum3, item3] | | [,itemnum4, item4] | | [,itemnum5, item5] ) | | where: BA = Byte array | | I = Integer | | IV = Integer value| _____________________________________________________________________________ Parameters envID (input/output) 52-byte character array. Specifies environment with matching environment identifier. See the discussion for an explanation of the use of envID, envIDlength, and envnum. envIDlength (input/output) 16-bit integer, by reference. Length of environment ID in bytes. See the discussion for an explanation of the use of envID, envIDlength, and envnum. envnum (input/output) 16-bit integer, by reference. Specifies environment by environment number. See the discussion for an explanation of the use of envID, envIDlength, and envnum. status (output) 16-bit integer, by reference. If the intrinsic call was successful, 0 is returned. Otherwise, an environment error number is returned.
NOTE The following parameters appear in pairs to identify an item of data. One to five item pairs may be specified in the call. For brevity, all five item pairs will be described as itemnum i and item i, where i is 1, 2,...5.
itemnum i (input) 16-bit integer, by value. Item number identifying the item i service to be performed. item i (output) Data type varies. By reference. Value of the item specified by the corresponding itemnum i; the data type of the item value depends on the item itself. Valid itemnums and the corresponding items are : 1. node length 16-bit integer. Length of the following node name item, in bytes. This item must precede item 2. 2. node 52-byte character array. Name of the node where the environment is located. This item must be preceded by item 1. 3. logon length 16-bit integer. Length of the following logon length item, in bytes. This item must precede item 4. 4. logon 54-byte character array Logon string (for example, user.acct,group) used to log on environment session. This item must be preceded by item 3. 5. trace information Array of 25 16-bit integers. Information about tracing of one service's NetIPC messages to the remote environment. In an NSINFO call using this item, the first word of the array must be set to the service for which the trace information is to be retrieved. The remainder of the fields will be filled in with the data by NSINFO. The array has the format shown in Figure 1-3. Service number Number identifying what service this trace information on record pertains to. 0 = All services 1 = VT 2 = NFT 3 = RFA 4 = RDBA 5 = RPMFigure 1-3. NSINFO Trace Information Data Structure TS If the service is being traced, this value is1; otherwise, this value is 0. TT If the transport is being traced, its value is 1; otherwise, its value is 0 . 6. establishment event 16-bit integer. Event (that is, command) that set up the environment. Values are: 0 = Environment created by a DSLINE command. 1 = Environment created by a REMOTE command. 7. compression 16-bit logical. If true (odd), data compression will be used when data is transmitted on the service's connection. Currently, NFT and RFA allow data compression. All other services will ignore the compression setting. 8. NFT service 16-bit logical. If true (odd), a process in this job or session has requested NFT service on some environment. This item is independent of the environment specified by envID or envnum. 9. prompt length 16-bit integer. Length of the following prompt string, in bytes. This item must precede item 10. 10. prompt 8-byte character array. String to be used as the REMOTE mode prompt. Item 9 must precede this item. 11. VT service 16-bit logical. If true (odd), then VT service has been established on the environment. If false (even), there is no VT service for the environment. 12. RFA service 16-bit logical. If true (odd), then RFA service has been established on the remote environment. If false (even), there is no RFA service for the environment. 13. node envnums length 16-bit integer. Contains the number of envnums entered into the array supplied by item 14. If 0 is returned, then no environments are defined on the node specified in envID. This item must precede item 14. 14. node envnums Array of 100 16-bit integers. Will be filled with the envnums of environments defined on the node whose name is specified in envID. Must be preceded by item 13. 16. logged on 16-bit logical. If true (odd), a remote session has been logged on for the environment. If false (even), there is no remote session for the environment. 18. local node length 16-bit integer. The length, in bytes, of the name of the local node. This item is independent of the environment specified by envID or envnum. It must precede item 19. 19. local node name 52-byte character array. The name of the local node. This item must be preceded by item 18. 21. service use count 16-bit integer. Count of the number of services currently sharing the environment. 25. RPM son 16-byte integer. If true (odd), the remote environment contains an RPM son process. If false (even), the RPM service is not active for the environment. 26. list environments length 16-bit integer. Contains the number of envnums entered into the array supplied in item 27. If0 is returned then no environments matched generic environment ID. This item must precede item 27. 27. list environments Array of 100 16-bit integers. Will be filled with envnums whose envID matches the generic environment ID input as the envID parameter. Must be preceded by item 26 . Description The NSINFO intrinsic is used to obtain information associated with environments defined in a job or session. There are two different ways that this intrinsic may be called. In the first method, envID / envnum define the specific environment or generic environment for which information is desired. In the second method, envID specifies the node name for which node-specific information is desired. Selection of the environment may be done by environment ID string or by environment number. The presence and value of the envID, envIDlength, and envnum parameters determine which mode is used. Also, these parameters are both input and output; the selected environment's ID or number can be retrieved through them. The rules for using the envID, envIDlength, and envnum are: * If envID and envIDlength are specified, and envIDlength is greater than 0, the environment will be determined by the environment ID in envID. If envnum is specified and its value is 0, the environment number will be determined by the environment specified in envID. * If envID and envIDlength are omitted, or if envIDlength is 0, the environment will be selected by the environment number in envnum. If envID and envIDlength are specified, and envIDlength is0, they will be set to the environment ID string and its length. * If envID and envIDlength are omitted or envIDlength is 0, and envnum is 0, the default environment will be selected. The default environment number will be returned in envnum, and its environment ID string and length will be returned in envID and envIDlength respectively, if specified. * Some services interpret envID as either a node name or a generic environment ID (such as items 26, 27 and 13, 14). In calls that use an item number such as this, envID and envIDlength are required parameters. * For services that are not dependent on any environment specification (such as items 8 or 18, 19), envID, envIDlength, and envnum are not required parameters. Items that flag a certain condition, such as item 16 (logged on status) or 12 (RFA service established), will return either an odd (TRUE) or an even (FALSE) value. This intrinsic may not be called in split stack mode. Errors Table 1-1 lists the errors that are returned in status upon completion of an NSINFO call. If an error is returned, all data returned from the call should be disregarded. Table 1-1. NSINFO Errors --------------------------------------------------------------------------------------------- | | | | Error Number | Meaning | | | | --------------------------------------------------------------------------------------------- | | | | 0 | No error. Successful return from NSINFO. | | | | --------------------------------------------------------------------------------------------- | | | | 1 | Required parameter missing. Either the envID and envIDlength or the | | | envnum; status must be specified. | | | | --------------------------------------------------------------------------------------------- | | | | 2 | Invalid itemnum value. | | | | --------------------------------------------------------------------------------------------- | | | | 3 | item parameter without a corresponding itemnum parameter. | | | | --------------------------------------------------------------------------------------------- | | | | 4 | itemnum parameter without a corresponding item parameter. | | | | --------------------------------------------------------------------------------------------- | | | | 5 | Invalid envID syntax. The correct syntax is | | | envID.domain.organization, with each part an alphanumeric string up | | | to 16 characters. | | | | --------------------------------------------------------------------------------------------- | | | | 10 | Invalid service in trace information array. Must be between 0 and | | | 6. | | | | --------------------------------------------------------------------------------------------- | | | | 20 | No environment entry exists for the selected environment. | | | | --------------------------------------------------------------------------------------------- | | | | 23 | The call selected the default environment, but no default environment | | | currently exists. | | | | --------------------------------------------------------------------------------------------- | | | | 24 | The value in envnum does not correspond to an existing environment. | | | | --------------------------------------------------------------------------------------------- | | | | 31 | Total length of a node name or envID is invalid. Must be 1 to 50 | | | characters. | | | | --------------------------------------------------------------------------------------------- | | | | 32 | First part ( node or envID) of a node name or envID does not begin | | | with an alphabetic character. | | | | --------------------------------------------------------------------------------------------- | | | | 33 | First part ( node or envID) of a node name or envID is longer than | | | 16 characters. | | | | --------------------------------------------------------------------------------------------- | | | | 34 | First part ( node or envID) of a node name or envID contains a | | | non-alphanumeric character. | | | | --------------------------------------------------------------------------------------------- NSINFO Errors(cont.) --------------------------------------------------------------------------------------------- | | | | Error Number | Meaning | | | | --------------------------------------------------------------------------------------------- | | | | 35 | The domain part of a node name or envID is missing. | | | | --------------------------------------------------------------------------------------------- | | | | 36 | The domain part of a node name or envID does not begin with an | | | alphabetic character. | | | | --------------------------------------------------------------------------------------------- | | | | 37 | The domain part of a node name or envID is longer than 16 | | | characters. | | | | --------------------------------------------------------------------------------------------- | | | | 38 | The domain part of a node name or envID contains a | | | non-alphanumeric character. | | | | --------------------------------------------------------------------------------------------- | | | | 39 | The organization part in a node name or envID is missing. | | | | --------------------------------------------------------------------------------------------- | | | | 40 | The organization part in a node name or envID does not begin with | | | an alphabetic character. | | | | --------------------------------------------------------------------------------------------- | | | | 41 | The organization part in a node name or envID is longer than 16 | | | characters. | | | | --------------------------------------------------------------------------------------------- | | | | 42 | The organization part in a node name or envIDcontains a | | | non-alphanumeric character. | | | | --------------------------------------------------------------------------------------------- | | | | 48 | Service requires more than one item (such as items 26, 27 or 9, 10) | | | and not all items required were supplied in the call. | | | | --------------------------------------------------------------------------------------------- | | | | 96 | DB is not pointing to the caller's stack; that is, NSINFO was called | | | in split stack mode. | | | | --------------------------------------------------------------------------------------------- | | | | 97 | An item parameter was passed to NSINFO that pointed to an array that | | | was outside of the caller's legal stack space. | | | | --------------------------------------------------------------------------------------------- | | | | 98 | Insufficient stack space for execution of procedure. | | | | ---------------------------------------------------------------------------------------------
![[]](../../pic3k/M010442/FIG133c50.gif)