3.166.1 VCB Structure

typedef struct query_userid_password
{
   AP_UINT16         opcode;                  /* Verb operation code         */
   unsigned char     reserv2;                 /* reserved                    */
   unsigned char     format;                  /* reserved                    */
   AP_UINT16         primary_rc;              /* Primary return code         */
   AP_UINT32         secondary_rc;            /* Secondary return code       */
   unsigned char     *buf_ptr;                /* pointer to buffer           */
   AP_UINT32         buf_size;                /* buffer size                 */
   AP_UINT32         total_buf_size;          /* total buffer size required  */
   AP_UINT16         num_entries;             /* number of entries           */
   AP_UINT16         total_num_entries;       /* total number of entries     */
   unsigned char     list_options;            /* listing options             */
   unsigned char     reserv3;                 /* reserved                    */
   unsigned char     user_id[10];             /* user ID                     */
} QUERY_USERID_PASSWORD;

typedef struct userid_info
{
   AP_UINT16              overlay_size;       /* size of returned entry      */
   unsigned char          user_id[10];        /* user ID                     */
   USERID_PASSWORD_CHARS  password_chars;     /* password characteristics    */
} USERID_INFO;

typedef struct userid_password_chars
{
   unsigned char          description[32];    /* resource description        */
   unsigned char          reserv2[16];        /* reserved                    */
   AP_UINT16              profile_count;      /* number of profiles          */
   AP_UINT16              reserv1;            /* reserved                    */
   unsigned char          password[10];       /* password                    */
   unsigned char          profiles[10][10];   /* profiles                    */
} USERID_PASSWORD_CHARS;

3.166.2 Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_USERID_PASSWORD

buf_ptr

A pointer to a data buffer that SNAP-IX will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of user ID / password pairs for which data should be returned. To request a specific entry rather than a range, specify the value 1. To return as many entries as possible, specify zero; in this case, SNAP-IX will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list from which SNAP-IX should begin to return data. Specify one of the following values:

AP_FIRST_IN_LIST

Start at the first entry in the list.

AP_LIST_INCLUSIVE

Start at the entry specified by the user_id parameter.

AP_LIST_FROM_NEXT

Start at the entry immediately following the entry specified by the user_id parameter.

For more information about how the list is ordered and how the application can obtain specific entries from it, see List Options For QUERY_* Verbs.

user_id

User ID. This is a 10-byte type-AE EBCDIC string, padded on the right with spaces if the name is shorter than 10 characters. The user ID is ignored if list_options is set to AP_FIRST_IN_LIST.

3.166.3 Returned Parameters: Successful Execution

If the verb executes successfully, SNAP-IX returns the following parameters:

primary_rc

AP_OK

buf_size

Length of the information returned in the supplied buffer.

total_buf_size

Returned value indicating the size of buffer that would have been required to return all the list information requested. A value greater than buf_size indicates that not all the available entries were returned.

num_entries

Number of entries returned in the data buffer.

total_num_entries

Total number of entries available. A value greater than num_entries indicates that not all the available entries were returned.

Each entry in the data buffer consists of the following parameters:

userid_info.overlay_size

The size of the returned userid_info structure, and therefore the offset to the start of the next entry in the data buffer.

When your application needs to go through the returned buffer to find each userid_info structure in turn, it must use this value to move to the correct offset for the next data structure, and must not use the C sizeof() operator. This is because the size of the returned overlay may increase in future releases of SNAP-IX; using the returned overlay size ensures that your application will continue to work with future releases.

userid_info.user_id

User identifier. This is a 10-byte type-AE EBCDIC character string, padded on the right with EBCDIC spaces.

userid_info.password_chars.description

A null-terminated text string describing the user ID and password, as specified in the definition of the user ID and password.

userid_info.password_chars.profile_count

Number of profiles defined for this user.

userid_info.password_chars.password

An encrypted version of the user's password supplied on a DEFINE_USERID_PASSWORD verb. This is a 10-byte type-AE EBCDIC character string, padded on the right with EBCDIC spaces.

userid_info.password_chars.profiles

Profiles associated with user. Each of these is a 10-byte type-AE EBCDIC character string, padded on the right with EBCDIC spaces.

3.166.4 Returned Parameters: Parameter Check

If the verb does not execute because of a parameter error, SNAP-IX returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_USERID

The list_options parameter was set to AP_LIST_INCLUSIVE to list all entries starting from the supplied user ID, but the user_id parameter was not valid.

AP_INVALID_LIST_OPTION

The list_options parameter was not set to a valid value.

Common Return Codes lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

3.166.5 Returned Parameters: Other Conditions

Common Return Codes lists further combinations of primary and secondary return codes that are common to all NOF verbs.