QUERY_3270

QUERY_3270_USER returns information about users of the SNAplus2 3270 emulation program. It can return either summary or detailed information, about a single user or multiple users, depending on the options used. This verb returns information about the user's current usage of 3270 emulation, not about the definition of this user in the configuration file; use QUERY_3270_USER_DEF to obtain information about the configuration file definition (such as session limits and access to 3270 functions), and QUERY_3270_USER_SESSIONS to obtain detailed information about individual sessions.

This verb must be issued to a running node.

VCB Structure

typedef struct query_3270_user
{
   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                       */
   AP_UINT16         scope;                /* parameters to match on         */
   unsigned char     user_name[32];        /* 3270 user name                 */
   unsigned char     system_name[64];      /* computer name                  */
   AP_UINT32         user_pid;             /* process ID                     */
} QUERY_3270_USER;

typedef struct user_3270_summary
{
   AP_UINT16    overlay_size;              /* size of returned entry         */
   unsigned char     user_name[32];        /* 3270 user name                 */
   unsigned char     system_name[64];      /* computer name                  */
   AP_UINT32         user_pid;             /* process ID                     */
} USER_3270_SUMMARY;

typedef struct user_3270_detail
{
   AP_UINT16         overlay_size;         /* size of returned entry         */
   unsigned char     user_name[32];        /* 3270 user name                 */
   unsigned char     system_name[64];      /* computer name                  */
   AP_UINT32         user_pid;             /* process ID                     */
   AP_UINT32         reserv1;              /* reserved                       */
   AP_UINT32         user_uid;             /* user ID                        */
   AP_UINT32         user_gid;             /* group ID                       */
   unsigned char     user_gname[32];       /* group name                     */
   AP_UINT32         user_session_count;   /* count of user's 3270 sessions  */
   AP_UINT32         user_start_time;      /* time when user started the     */
                                           /*  3270 emulation program        */
} USER_3270_DETAIL;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_3270_USER

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 users for which data should be returned. To request data for a specific user 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 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 entry in the list.

AP_LIST_INCLUSIVE

Start at the entry specified by the combination of the scope, user_name, system_name, and user_pid parameters (see below).

AP_LIST_FROM_NEXT

Start at the entry immediately following the entry specified by the combination of the scope, user_name, system_name, and user_pid parameters (see below).

The scope parameter specifies whether to filter the returned information by user name, computer name, process ID, or any combination of these. For more information about how the application can obtain specific entries from the list, see “List Options For QUERY_* Verbs”.

scope

The range of 3270 emulation users for which information should be returned. This is used in conjunction with the list_options parameter to specify which entries are required. Possible values are:

AP_USER: Return information about all 3270 emulation programs running with the specified user name, or on all 3270 users if no name is specified.
AP_SYSTEM: Return information about 3270 emulation programs running on the specified computer.
AP_USER_AT_SYSTEM: Return information about all 3270 emulation programs running with the specified 3270 user name on the specified computer.
AP_USER_PROCESS: Return information about a specific copy of the 3270 emulation program, identified by the 3270 user name, computer name, and process ID.

user_name

The name of the 3270 user for whom information is required, or the name to be used as an index into the list of users. The user name is an ASCII string of 1-32 characters. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST.

system_name

The computer name for which 3270 user information is required; this is an ASCII string of 1-64 characters. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST.

If you are running SNAplus2 with all programs on a single computer, you can set this parameter to all binary zeros; there is no need to specify the computer name. .

user_pid

The process ID of the 3270 emulation program for which information is required, or the process ID to be used as an index into the list of users. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST. If this parameter is specified and you are running SNAplus2 in a client-server configuration, the system_name parameter must also be specified.

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.

Each entry in the data buffer consists of the following:

user_3270_summary.overlay_size

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

user_3270_summary.user_name

The name of the 3270 user. This is an ASCII string of 1-32 characters.

user_3270_summary.system_name

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

user_3270_summary.user_pid

The process ID of the 3270 emulation program.

user_3270_detail.overlay_size

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

user_3270_detail.user_name

The name of the 3270 user. This is an ASCII string of 1-32 characters.

user_3270_detail.system_name

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

user_3270_detail.user_pid

The process ID of the 3270 emulation program.

user_3270_detail.user_uid

The HP-UX user ID with which the 3270 emulation program is running.

user_3270_detail.user_gid

The HP-UX group ID with which the 3270 emulation program is running.

user_3270_detail.user_gname

The HP-UX group name with which the 3270 emulation program is running.

user_3270_detail.user_session_count

The number of sessions currently active for this copy of the 3270 emulation program. The application can use the QUERY_3270_USER_SESSIONS verb to obtain detailed information about these sessions.

user_3270_detail.user_start_time

The time at which the user started the 3270 emulation program (this may be earlier than the start time for the first session). This value is specified as “seconds since epoch” (the number of seconds since the start of the year 1970).

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_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

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Other Conditions