QUERY_SIGNED_ON_LIST

QUERY_SIGNED_ON_LIST retrieves information about users signed on to a particular LU.

The local LU is specified by lu_name or lu_alias. Buf_ptr, buf_size, total_buf_size, num_entries, total_num_entries and overlay_size have the usual meanings for a QUERY verb.

Entries are returned as a list of SIGNED_ON_LIST_ENTRY structures, pointed to by buf_ptr, or appended to the QUERY_SIGNED_ON_LIST VCB if buf_ptr is NULL. The list is ordered by plu_alias/fqplu_name, then by user_id and then by profile. If plu_alias is specified, fqplu_name is ignored.

The list_options can take the values AP_FIRST_IN_LIST, AP_LIST_FROM_NEXT, AP_LIST_INCLUSIVE. If list_options is AP_FIRST_IN_LIST, plu_alias, fqplu_name, user_id, and profile are ignored. The list specifies which list to return entries from, which must be AP_SIGNED_ON_TO_LIST.

VCB Structure

typedef struct query_signed_on_list
{
   unsigned short  opcode;            /* verb operation code          */
   unsigned char   reserv2;           /* reserved                     */
   unsigned char   format;            /* format                       */
   unsigned short  primary_rc;        /* primary return code          */
   unsigned long   secondary_rc;      /* secondary return code        */
   unsigned char   *buf_ptr;          /* pointer to buffer            */
   unsigned long   buf_size;          /* buffer size                  */
   unsigned long   total_buf_size;    /* total buffer size required   */
   unsigned short  num_entries;       /* number of entries            */
   unsigned short  total_num_entries; /* total number of entries      */
   unsigned char   list_options;      /* listing options              */
   unsigned char   reserv3;           /* reserved                     */
   unsigned char   lu_name[8];        /* LU name                      */
   unsigned char   lu_alias[8];       /* LU alias                     */
   unsigned char   plu_alias[8];      /* partner LU alias             */
   unsigned char   fqplu_name[17];    /* fully qualified partner      */
                                      /* LU name                      */
   unsigned char   user_id[10];       /* User ID                      */
   unsigned char   profile[10];       /* Profile                      */
   unsigned char   list;              /* Signed-on list type          */
} QUERY_SIGNED_ON_LIST;
typedef struct signed_on_list_entry
{
   unsigned short  overlay_size;      /* size of this entry           */
   unsigned char   plu_alias[8];      /* partner LU alias             */
   unsigned char   user_id[10];       /* fully qualified partner      */
   unsigned char   profile[10];       /* profile                      */
} SIGNED_ON_LIST_ENTRY;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_SIGNED_ON_LIST
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr
Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information.

The combination of lu_name (or lu_alias if the lu_name is set to all zeros), pu_alias (or fqplu_name if the plu_alias is set to all zeros), user_id and profile specified (see the following parameters, lu_name, pu_alias, user_id, and profile) represent an index value that is used to specify the starting point of the actual information to be returned .

AP_FIRST_IN_LIST
The pu_alias, fqplu_name, user_id, and profile are ignored and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE
The returned list starts from the entry specified by the index value.
lu_name
LU name. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the index.
lu_alias
Locally defined LU alias. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_name and the lu_alias fields are set to all zeros, the LU associated with the control point (the default LU) is used.
plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. If this field is set to all zeros, the fqplu_name field will be used for determining the index.
fqplu_name
17-byte fully qualified network name for the partner LU. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
user_id
User ID. This should be set to a 10–byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. If this field is set then only sessions associated with this mode are returned. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
profile
This is a 10-byte alphanumeric EBCDIC string. Note, the Program currently supports only the blank profile (10 eBCDIC spaces). This field is ignored if list_options is set to AP_FIRST_IN_LIST.
list
Signed–on list type. This must be set to AP_SIGNED_ON_TO_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries
Number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
signed_on_list_entry.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
signed_on_list_entry.plu_alias
Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
signed_on_list_entry.user_id
User ID. This is a 10-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
signed_on_list_entry.profile
10-byte alphanumeric EBCDIC string.
Note:
The Program currently supports only the blank profile (10 EBCDIC spaces).
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_LU_ALIAS

AP_INVALID_LU_NAME
AP_INVALID_PLU_NAME
AP_INVALID_USERID
AP_INVALID_PROFILE
AP_INVALID_LIST
AP_INVALID_LIST_OPTION

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because the node stopped, the Program returns the following parameter:
primary_rc
AP_NODE_STOPPING