QUERY_3270_USER

QUERY_3270_USER returns information about a 3270 emulation user's current sessions. It can return either summary or detailed information, about a single session or multiple sessions, depending on the options used. The application can use QUERY_EMULATOR_USER_DEF to obtain information about the configuration file definition of a 3270 user (such as session limits and access to 3270 functions), and QUERY_3270_USER to obtain general information about the user's 3270 emulation program usage.

This verb must be issued to a running node.

VCB Structure

typedef struct query_3270_user_sessions
{
    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_name[32];        /* 3270 user name                */
    unsigned char     system_name[64];      /* computer name                 */
    AP_UINT32         user_pid;             /* process ID                    */
    unsigned char     lu_name[8];           /* LU of session to start from   */
} QUERY_3270_USER_SESSIONS;

typedef struct user_3270_session_summary
{
    AP_UINT16         overlay_size;         /* size of returned entry        */
    unsigned char     lu_name[8];           /* LU used by session            */
} USER_3270_SESSION_SUMMARY;

typedef struct user_3270_session_detail
{
    AP_UINT16         overlay_size;         /* size of returned entry        */
    unsigned char     lu_name[8];           /* LU used by session            */
    unsigned char     nau_address;          /* NAU adddress of LU            */
    AP_UINT32         reserv1[3];           /* reserved                      */
} USER_3270_SESSION_DETAIL;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_3270_USER_SESSIONS

overlay_size

For compatability with future releases of SNAplus2, your application must use this field to determine the exact length of the overlay structure returned, and should not rely on the use of the sizeof() function.

buf_ptr

A pointer to a data buffer that SNAplus2 will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of sessions for which data should be returned. To request data for a specific session rather than a range, specify the value 1. To return as many entries as possible, specify zero; in this case, SNAplus2 will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list of sessions from which SNAplus2 should begin to return data, and the level of information required for each entry. Specify the level of information with one of the following values:

AP_SUMMARY

Summary information only.

AP_DETAIL

Detailed information.

Combine this value using a logical OR operation with one of the following values:

AP_FIRST_IN_LIST

Start at the first session in the list.

AP_LIST_INCLUSIVE

Start at the entry specified by the lu_name parameter.

AP_LIST_FROM_NEXT

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

For more information about how the application can obtain specific entries from the list, see “List Options For QUERY_* Verbs”.

user_name

The name of the 3270 user for whom information is required; this is an ASCII string of 1-32 characters. This parameter must be specified.

system_name

The computer name for which 3270 user information is required; this is an ASCII string of 1-64 characters. .

If the SNAplus2 system includes only one server, there is no need to specify the computer name (it can be left as all binary zeros). If there are multiple servers and no computer name is specified, SNAplus2 returns the first entry it finds for the specified user name; there is no need to specify the computer name unless the specified user is using the 3270 emulation program on more than one computer.

user_pid

The process ID of the 3270 emulation program for which information is required.

If the SNAplus2 system includes only one server, this parameter is required only if the user is using more than one copy of the 3270 emulation program. If there are multiple servers and no process ID is specified, SNAplus2 returns the first entry it finds for the specified user name; there is no need to specify the process ID unless the specified user is using more than one copy of the 3270 emulation program on the computer specified by the system_name parameter. If the process ID is not required, set it to zero.

lu_name

The LU used by the session for which information is required, or the LU name to be used as an index into the list of sessions. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST. The name is an 8-character EBCDIC string, padded on the right with EBCDIC spaces if necessary.

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 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 may be higher than buf_size.

total_num_entries

Total number of entries that could have been returned. This may be higher than num_entries.

num_entries

The number of entries actually returned.

system_name

The computer name on which the 3270 emulation program is running.

user_pid

The process ID of the 3270 emulation program.

Each entry in the data buffer consists of the following:

user_3270_session_summary.overlay_size

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

user_3270_session_summary.lu_name

The LU being used by the session.

user_3270_session_detail.overlay_size

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

user_3270_session_detail.lu_name

The LU being used by the session.

user_3270_session_detail.nau_address

The NAU address of the LU used by the 3270 session.

Returned Parameters: Parameter Check

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

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_3270_USER: The user_name, system_name, or user_pid parameter was not set to a valid value.
AP_INVALID_3270_SESSION: The lu_name parameter was not set to a valid value.
AP_INVALID_LIST_OPTION: The list_options parameter was not set to a valid value.

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

Returned Parameters: Other Conditions

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

QUERY_3270_USER_SESSIONS

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Other Conditions