 |
» |
|
|
 |
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. 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.
|