DEFINE_EMULATOR

DEFINE_EMULATOR_USER identifies a user of the SNAplus2 system that can use 3270 emulation or 5250 emulation, and defines the resources available to that user. It can be used to define a new user, to define new sessions for use by an existing user, or to modify the user parameters and session parameters for an existing user. (To delete sessions from an existing user, use DELETE_EMULATOR_USER.)

This verb must be issued to the domain configuration file.

VCB Structure

The DEFINE_EMULATOR_USER verb contains a variable number of session_def_data structures; these define the user's sessions and (optionally) the user's remap list. The session structures are included at the end of the def_data structure; the number of these structures is specified by the num_sessions parameter.

typedef struct define_emulator_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            user_name[32];     /* 3270 user name             */
   EMULATOR_USER_DEF_DATA   def_data;
} DEFINE_EMULATOR_USER;

typedef struct emulator_user_def_data
{
   unsigned char   description[32];   /* Description - null terminated       */
   unsigned char   reserv3[16];       /* reserved                            */
   unsigned char   style_file[9];     /* Initial 3270 style file name        */
                                      /*  - null terminated                  */
   unsigned char   reserv1[3];        /* reserved                            */
   AP_UINT32       num_sessions;      /* Number of sessions being added      */
   AP_UINT32       max_act_sessions;  /* Max number of active 3270 sessions  */
   unsigned char   view_rtm;          /* Can user view RTM info?             */
   unsigned char   alert_permission;  /* Can user send alerts?               */
   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;  /* reserved                            */
   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;
} 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_DEFINE_EMULATOR_USER

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.

user_name

The name of the user or group. This is an ASCII string of 1-32 characters, padded on the right with spaces if the name is shorter than 32 characters, which must be one of the following:

The HP-UX user ID of a 3270 or 5250 user on the SNAplus2 computer (or, for a Windows Client user, the user name specified in the SNAplus2 client network data file). The user_is_group parameter below must be set to AP_NO.
The HP-UX group ID of a group of 3270 or 5250 user on the SNAplus2 computer (or, for a Windows Client user, the group name specified in the SNAplus2 client network data file). The user_is_group parameter below must be set to AP_YES.

To set up a default record, which will be used by any user not explicitly named in the configuration, specify the name <DEFAULT> (in uppercase and including the angle bracket characters), and set user_is_group to AP_NO. To restrict use of the emulation program to users and groups that are explicitly named in the configuration, do not include a <DEFAULT> record.

When the user starts the emulation program, SNAplus2 checks the user ID against the emulator user records in the configuration to find the correct record, in the following order:

If the user ID matches a record for a specific user name, this record is used.
If the user ID cannot be matched but the user's group ID matches a record for a group, this record is used.
If neither the user ID nor the group ID can be matched, but there is a <DEFAULT> record defined, this record is used.

def_data.description

An optional text string (0-31 characters followed by a null character). The string is for information only; it is stored in the configuration file and returned on the QUERY_EMULATOR_USER_DEF verb, but SNAplus2 does not make use of it. You can use it to store additional information such as the user's full name, to help distinguish between users.

def_data.style_file

The name of this user's default style file. This is a string of 1-8 characters, followed by a null character. For HP-UX, the actual file name used is the name specified here with the extension .stu (3270) or .stx (5250) appended to it. For Windows, check the emulator documentation for details of style file naming conventions.

def_data.num_sessions

The number of sessions (3270, 5250, or both) being defined or modified by this verb. Each session must be specified by a session_def_data structure following the def_data structure.

def_data.max_act_sessions

The maximum number of 3270 sessions that this user can access simultaneously. (For a 5250-only user, this field is ignored.) Use this field as follows:

To prevent the user from using 3270 emulation, set this field to zero.
To restrict the number of sessions that the user can use simultaneously, set this field to a value between 1 and 10 (or between 1 and the total number of sessions defined for the user, if this is less than 10).
To specify no limit, set this field to 0xFFFFFFFF.

def_data.view_rtm

Specifies whether the user has permission to view Response Time Monitor (RTM) data. This also determines whether the Last Transaction Time Indicator (LTTI) is displayed on the 3270 status line. (For a 5250-only user, this field is ignored.) Possible values are:

AP_YES: The user can view RTM data; the LTTI is displayed.
AP_NO: The user cannot view RTM data; the LTTI is not displayed.

def_data.alert_permission

Specifies whether the user has permission to send 3270 user alerts. (For a 5250-only user, this field is ignored.) Possible values are:

AP_YES: The user can send alerts.
AP_NO: The user cannot send alerts.

def_data.change_lu

Specifies whether the user has permission to change the mapping of 3270 sessions to LUs, either by remapping them from within the 3270 user interface, or by specifying LU names on the command line when starting the 3270 emulation program. (For a 5250-only user, this field is ignored.) Possible values are:

AP_YES: The user can change the LU/session mapping.
AP_NO: The user cannot change the LU/session mapping.

def_data.change_style

Specifies whether the user has permission to load style files, modify style files, or both. Possible values are:

AP_STYLE_ADVANCED

The user can specify a style file name when starting the emulation program, and can create or modify style files using the emulation program's menu interface.

AP_STYLE_NORMAL

The user can specify a style file name when starting the emulation program, and can create or modify style files using the emulation program's menu interface. The user cannot modify the default style file specified by the style_file parameter.

The 3270 emulation program does not distinguish between the two values AP_STYLE_ADVANCED and AP_STYLE_NORMAL; to prevent users from modifying the default style file, set the permissions on this file so that users do not have write access to it.

AP_STYLE_INITIAL

The user can specify a style file name on the command line when starting the emulation program, but cannot load, create, or modify style files from within the menu interface. This option allows you to provide a choice of standard initial style files for a user.

AP_STYLE_RESTRICTED

The user is restricted to the default style file specified by the style_file parameter, and cannot create or modify style files.

def_data.user_is_group

Specifies whether the user_name parameter identifies a user name or a group name. Possible values are:

AP_YES: The user_name parameter identifies a group name. Any user in this group will use this emulator user record unless there is an explicit record for the user's user name.
AP_NO: The user_name parameter identifies a user name.

For each session being defined by this verb, up to the number specified in num_sessions, a session_def_data structure is required with the following information:

session_def_data.session_name

A name identifying the session. This is an 8-byte ASCII string, padded on the right with spaces if the name is shorter than 8 characters. If the name matches an existing session name defined for this user, the information for that session is replaced; otherwise a new session is added.

To define 3270 sessions that are initially displayed in the 3270 emulation program's control interface, specify a name in the range SESS0001-SESS0010. These names correspond to the session numbers 1-10 in the control interface; that is, if you use the names SESS0002, SESS0003, and SESS0005, the control interface will display session numbers 2, 3, and 5 using the information defined for these names. (The names SESS0001-SESS0010 are not displayed in the control interface; they are replaced by the long names defined for these sessions in the 3270 style file.)

3270 sessions that are available for the user to remap to must be given names that are not in the range above. The user will be able to access these sessions only if the change_lu parameter (see above) allows the user to remap sessions.

session_def_data.emulator_type

Type of the emulation program that uses this session. Possible values are:

AP_3270_SESSION: Session used for 3270 emulation
AP_5250_SESSION: Session used for 5250 emulation

session_def_data.description

For a 3270 session, the following fields are included:

session_def_data.session_variant.def_data_3270.lu_name

Name of the LU or LU pool that this session uses. This is an 8-byte EBCDIC string, padded on the right with EBCDIC spaces. It must match the name of a type 0-3 LU or LU pool that has already been defined.

If you assign the session to an LU that is in an LU pool, SNAplus2 will try to use this LU when the session is activated. If the LU is not available, SNAplus2 will then attempt to find a free LU from the pool (as though the session had been assigned to the pool).

session_def_data.session_variant.def_data_3270.session_type

Type of the LU or pool (display or printer, and the screen model for display LUs). Possible values are:

AP_3270_DISPLAY_MODEL_2: Display model 2 (80 x 24)
AP_3270_DISPLAY_MODEL_3: Display model 3 (80 x 32)
AP_3270_DISPLAY_MODEL_4: Display model 4 (80 x 43)
AP_3270_DISPLAY_MODEL_5: Display model 5 (132 x 27)
AP_PRINTER: Printer LU. (This value is not valid if lu_name specifies an LU pool.)

session_def_data.session_variant.def_data_3270.model_override

Specifies whether the user has permission to change the session to use a different screen model from the one specified. Possible values are:

AP_YES: The user can change the screen model.
AP_NO: The user cannot change the screen model.

For a 5250 session, the following fields are included:

session_def_data.session_variant.def_data_5250.local_lu_alias

LU alias of the local LU that this session uses. This is an 8-byte ASCII string (starting with a letter), padded on the right with spaces. It must match the alias of an APPC local LU that has already been defined.

session_def_data.session_variant.def_data_5250.plu_alias

LU alias of the partner LU that this session uses. This is an 8-byte ASCII string (starting with a letter), padded on the right with spaces. It must match the alias of an APPC partner LU that has already been defined. For more information, see “Defining Partner LUs”.

To indicate that the partner LU is identified by its fully qualified name instead of its LU alias, set this parameter to 8 binary zeros, and specify the fully qualified name in the fqplu_name parameter.

session_def_data.session_variant.def_data_5250.fqplu_name

Fully qualified name of the partner LU that this session uses. This parameter is used only if plu_alias is set to zeros; it is ignored otherwise. For more information, see “Defining Partner LUs”.

The name is a 17-byte EBCDIC string, right-padded with EBCDIC spaces. It consists of a network ID of up to 8 A-string characters, an EBCDIC dot (period) character, and a network name of up to 8 A-string characters.

session_def_data.session_variant.def_data_5250.mode_name

Name of the mode that this session uses. This is an 8-byte type-A EBCDIC string (starting with a letter), padded on the right with EBCDIC spaces. The mode name must match the name of an APPC mode that has already been defined; it is generally set to the SNA-defined mode name QPCSUPP.

session_def_data.session_variant.def_data_5250.session_type

Type of the 5250 session (display or printer). Possible values are:

AP_5250_DISPLAY: Display session
AP_5250_PRINTER: Printer session

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 returns the following parameter:

primary_rc: AP_OK

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

AP_INVALID_SESSION_TYPE: The emulator_type or session_type parameter for one or more sessions 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.

Defining Partner LUs

This verb allows you to specify the partner LU using either its fully qualified LU name or its LU alias. If you specify the fully qualified name, no additional configuration of the partner LU is required; if you specify the LU alias, you must also use DEFINE_PARTNER_LU to define the fully qualified name corresponding to this alias, so that SNAplus2 can locate the LU when it is required by a session.

If the 5250 emulation program requires LUs to be specified by LU alias rather than by fully qualified name (this applies to many Windows-based 5250 emulation programs that use the WinSNA APIs), you must specify the LU alias on this command, and use DEFINE_PARTNER_LU as above.

DEFINE_EMULATOR_USER

Technical documentation

» Table of Contents