Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX SNAplus2 NOF Programmers Guide: HP-UX 11i > Chapter 4 NOF API Verbs (QUERY Verbs)

QUERY_EMULATOR_USER_DEF

» 

Technical documentation

Complete book in PDF
» Feedback
Content starts here

 » Table of Contents

 » Index

QUERY_EMULATOR_USER_DEF returns information about 3270 users or 5250 users defined in a SNAplus2 configuration file. 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 definition of this user in the configuration file, not about the user's current usage of the emulation program. You can use QUERY_3270_USER and QUERY_3270_USER_SESSIONS to obtain information about a user's current 3270 emulation usage.

This verb must be issued to the domain configuration file.

VCB Structure

typedef struct query_emulator_user_def
{
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 session_name[8]; /* session name */
unsigned char emulator_type; /* type of entries to return */
unsigned char reserv4; /* reserved */
AP_UINT32 num_init_sessions; /* number of sessions for first */
/* user when starting in middle */
AP_UINT32 num_last_sessions; /* number of sessions on last */
/* detail overlay if last user */
/* is incomplete */
unsigned char last_user_incomplete; /* set to AP_YES if session */
/* data for last user incomplete */
} QUERY_EMULATOR_USER_DEF;
typedef struct emulator_user_summary
{
unsigned char user_name[32]; /* user name */
} EMULATOR_USER_SUMMARY;
typedef struct emulator_user_detail
{
unsigned char user_name[32]; /* user name */
AP_UINT32 num_filtered_sessions; /* total number of sessions */
/* of the requested type */
EMULATOR_USER_DEF_DATA def_data; /* user definition */
} EMULATOR_USER_DETAIL;
typedef struct emulator_user_def_data
{
unsigned char description[32]; /* Description - null terminated */
unsigned char reserv3[16]; /* reserved */
unsigned char style_file[9]; /* Initial style file name */
/* - null terminated */
unsigned char reserv1[3]; /* reserved */
AP_UINT32 num_sessions; /* Number of sessions */
AP_UINT32 max_act_sessions; /* Maximum number of active sessions */
unsigned char view_rtm; /* Can user view RTM info? */
unsigned char alert_permission; /* Has user got ALERT permission? */
unsigned char change_lu; /* Can user change LU/Pool accessed? */
unsigned char change_style; /* Can user modify initial style file?*/
unsigned char user_is_group; /* Does user_name specify a */
/* HP-UX group? */
unsigned char status; /* reserved */
unsigned char reserv2; /* reserved */
} EMULATOR_USER_DEF_DATA;
typedef struct session_def_data
{
AP_UINT16 sub_overlay_size; /* size of session_def_data structure */
unsigned char session_name[8]; /* Long session name */
unsigned char emulator_type; /* Emulator type - 3270 or 5250 */
unsigned char reserv1; /* reserved */
unsigned char description[32]; /* Session description */
unsigned char reserv2[16]; /* reserved */
union
{
SESSION_3270_DEF_DATA def_data_3270; /* definition of 3270 session */
SESSION_5250_DEF_DATA def_data_5250; /* definition of 5250 session */
} session_variant;
AP_UINT32 reserv4; /* reserved */
} SESSION_DEF_DATA;
typedef struct session_3270_def_data
{
unsigned char lu_name[8]; /* LU/pool name accessed */
unsigned char session_type; /* Session type - Model 2-5 or printer*/
unsigned char model_override; /* Can the user override the model? */
} SESSION_3270_DEF_DATA;
typedef struct session_5250_def_data
{
unsigned char local_lu_alias[8]; /* Local LU alias */
unsigned char plu_alias[8]; /* Partner LU alias */
unsigned char fqplu_name[17]; /* Fully-qualified partner LU name */
unsigned char mode_name[8]; /* Mode name */
unsigned char session_type; /* Session type - display or printer */
} SESSION_5250_DEF_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_EMULATOR_USER_DEF

sub_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. If detailed information about user sessions is being returned, this number includes partial entries (for which a session name is specified, so that the returned data does not include the user definition or the user's first session).

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 session for the first user in the list.

AP_LIST_INCLUSIVE

Start at the entry specified by the supplied user name and session name, or start at the first session for the specified user if no session name is specified.

AP_LIST_FROM_NEXT

If a session name is specified, start at the session immediately following the specified session. If no session name is specified, start at the first session for the specified user.

The list is ordered by user name, and then by session name (irrespective of session type) for each user. 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_name

The name of the user for whom information is required, or the name 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. The name is an ASCII string of 1-32 characters, padded on the right with spaces if the name is shorter than 32 characters.

session_name

To return information starting with a specific session name for the specified user, set this parameter to the session name. To return information starting at the first session for the specified user, set this parameter to 8 binary zeros.

emulator_type

Specify whether to filter the returned information by session type. Possible values are:

AP_3270_SESSION

Return only information about 3270 sessions.

AP_5250_SESSION

Return only information about 5250 sessions.

AP_ALL

Return information about all sessions regardless of session type.

AP_NONE

Do not return any session_def_data structures. This value can be used with list_options set to AP_DETAIL, to obtain detailed information about each user's style file and 3270 permissions but to suppress detailed information about individual sessions.

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. The last entry may be incomplete; this is indicated by the last_user_incomplete parameter.

num_init_sessions

If the session_name parameter was set to a nonzero value, so that the information for the first user in the list does not start with the user's first session, this parameter indicates the number of session structures for this user that are included in the returned data. Otherwise, this parameter is not used.

num_last_sessions

If the last_user_incomplete parameter indicates that the data for the last user is incomplete, this parameter indicates the number of session structures for this user that are included in the returned data. (The num_filtered_sessions parameter returned for this user indicates the total number of session structures of the requested type that are available.) Otherwise, this parameter is not used.

last_user_incomplete

Specifies whether the information for the last user is incomplete. Possible values are:

AP_YES

The complete data for the last user was too large to fit in the data buffer. At least one session structure is included, but there are further session structures that are not included in the data buffer. The num_last_sessions parameter indicates how many session structures have been returned; the application can issue further verbs to obtain the remaining data.

AP_NO

The data for the last user is complete.

Each entry in the data buffer consists of the following:

emulator_user_summary.user_name

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

emulator_user_detail.user_name

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

emulator_user_detail.num_filtered_sessions

The total number of sessions for this user of the type(s) specified by emulator_type. If emulator_type was set to AP_NONE, this parameter is zero.

emulator_user_detail.def_data

The details of the user, as defined in the configuration. This is followed by a number of session structures, defining the user's sessions and the user's remap list. The format of this information is the same as for the DEFINE_EMULATOR_USER verb, except for the following:

  • The sub_overlay_sizedef_data parameter in the structure specifies the size of each returned session_def_data structure, and therefore the offset to the start of the next entry in the data buffer.

  • The num_sessions parameter in the def_data structure defines the total number of sessions (3270, 5250, or both) defined for the user.

  • If the session_name parameter was set to a nonzero value, the data for the first user will contain only the remaining session structures (starting from the requested entry), without the def_data structure.

  • If the last_user_incomplete parameter is set to AP_YES, the total number of session structures returned for the last user will be as specified by the num_last_sessions parameter; this will be less than num_sessions.

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_EMULATOR_USER

The list_options parameter was set to AP_LIST_INCLUSIVE, but the user_name parameter did not match the name of any defined user.

AP_INVALID_SESSION_NAME

The list_options parameter was set to AP_LIST_INCLUSIVE, but the session_name parameter did not match a session name defined for the specified user.

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.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 2003 Hewlett-Packard Development Company, L.P.