|
|
|
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 I I (IV) (BA)
NSINFO ( [envID], [envIDlength], [envnum], status [,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. |
|
|
|
|
- inemnum 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 6-1 “NSINFO Trace Information Data Structure”.
Figure 6-1 NSINFO Trace Information Data Structure
![[NSINFO Trace Information Data Structure]](img/gfx6.gif)
- 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 = RPM - TS
If the service is being traced, this value is 1;
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. The
NS transport must have been started for this to succeed - 19. local node name
52-byte character array.
The name of the local node. This item must be preceded by item 18.
The NS transport must have been started for this to succeed. - 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. If 0
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. - 36. local node ARPA domain name length
16-bit integer. The length,
in bytes, of the local node's ARPA domain name. This item
is independent of the environment specified by envID
or envnum. It must precede item 37. The
NS transport must have been started for this to succeed. - 37. local node ARPA domain name
255-byte character array.
The name of the local node's ARPA domain name. The NS transport
must have been started for this to succeed. - 38. IP address
32-bit integer. The IP address
(4 bytes) of the node in the given environment. Currently, this
option works only for $BACK environments. The value zero will be
returned for all other environments.
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 is 0,
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 for the calling process 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.
Note: The default environment is defined per process not per job
or session. 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 6-1 “NSINFO
Errors” 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 6-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. | | 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
none was set by a prior :DSLINE or :REMOTE
command. | | 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. | | 35 | The domain part
of a node name or envID
is missing. | | 36 | The domain part
of a nodename
or envID does not begin with an alphabetic
character. | | 37 | The domain part
of a nodename
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 envID
contains a non-alphanumeric character | | 44 | NS transport not started. To start NS transport
execute the NETCONTROL START command. | | 45 | Unknown node | | 48 | A specified item requires another item | | 96 | DB is not pointing to the caller's
stack | | 97 | An item parameter was passed by reference to
NSINFO which was outside of the
caller's legal stack space. | | 98 | Insufficient stack space for execution of procedure. |
|
