Advanced Configuration

This chapter describes facilities useful for deploying Z and I Emulator for Windows in large networks. Some of these facilities are handled by features of Z and I Emulator for Windows itself, while others are provided by external products, augmented with facilities provided by Z and I Emulator for Windows.

Configuration Files

The following sections describe the advanced configurations that you can make with the built-in files of Z and I Emulator for Windows. Advanced configurations enable you to easily configure and distribute common keywords and parameters to your client base, and include the following:

Initial Configuration Definitions

Z and I Emulator for Windows enables network administrators to create an initial configuration definitions file that contains common configuration definitions for their clients. By using an initial configurations file, the administrator can distribute preconfigured definitions and have them automatically preloaded whenever a new configuration is created on a client.

The first step is to create a configuration using Start or Configure Sessions, or an ASCII editor. For detailed information on configuring sessions, refer to Quick Beginnings.

After you create the configurations file, rename the file to the appropriate reserved name. For workstation profiles (*.WS), the file name is PCSINIT.WS$.

After you rename the files, they can be distributed to client workstations. Put the files in the configuration files directory. The definitions in the files will be preloaded whenever a user creates a new configuration.

Note:
The initial configuration file does not override parameter defaults for new definitions in new configurations, but preloads complete definitions into new configurations. Users can modify these definitions to get custom parameter values; however, the original initial configuration file remains unchanged.

Configuration File and Emulator Profile Directories

The default directory for configuration files is specified during installation. Configuration files can be used for all users or a specific user. Refer to CD-ROM Guide to Installation for details on specifying the initial default directory.

By default, Z and I Emulator for Windows searches for emulator profiles in the configuration files directory. You can use the User Preference Manager utility to indicate a different location for profiles.

Using Template and Update Files

When creating configurations for a large number of clients to implement, you can create a template configuration file that represents the common configuration elements for all clients. Using an update file with only those changes necessary for each client, you can distribute the template and update file and merge the two to create the target configuration.

The Z and I Emulator for Windows Server template and update files enable you to create or modify a configuration using an ASCII editor. You can configure all of the Z and I Emulator for Windows configuration keywords and parameters with update files.

Template files can ease the mass distribution of configurations to remote clients. A template file can specify the keywords which are common to several clients. For example, if you have multiple clients to configure, many of the keywords will be identical. You can create a template configuration file that reflects those common keywords.

You can use update files to add, modify, or delete keywords in a template file. The original template configuration file is left unchanged. An update file is merged into a template file by specifying the INCLUDE keyword at the end of the template file. For example, if an update file is named myconfig.chg, the last line of the template file that will use the update file is INCLUDE=myconfig.chg. When the template file and the update file are merged, you can give the resulting configuration file a name with the .ACG extension that distinguishes it from other .ACG files.

Key Fields

The key field is the parameter in a keyword that names the keyword and uniquely identifies it from other keywords of the same type.

Some keywords do not have key fields because they can only be specified once in a configuration file. An example of a keyword that can only be specified once is the NODE keyword.

Adding Keywords to a Template File

When using an update file to add a new keyword definition, you must provide the entire keyword. The key field must be provided along with a unique value. If any subfields are omitted from the keyword, the defaults for those fields are used. For example, to add a MODE keyword to the configuration, the update file might contain the following keyword:

MODE=(
     MODE_NAME=MYMODE
     COS_NAME=#INTER
     CRYPTOGRAPHY=NONE
     DEFAULT_RU_SIZE=1
     MAX_NEGOTIABLE_SESSION_LIMIT=128
     MAX_RU_SIZE_UPPER_BOUND=4096
     MIN_CONWINNERS_SOURCE=15
)

The content of the update file assumes that a MODE keyword with the parameter of MODE_NAME=MYMODE does not exist in the template. If it does, the parameters will be updated with the values provided in the update file.

If the MODE_NAME parameter is omitted from the update file, an error will occur during the configuration verification because the MODE_NAME parameter cannot be uniquely identified. Not all parameters available for the MODE keyword are specified in the update file. The remaining parameters use the defaults as specified in Configuration File Reference. The resulting addition to the configuration will look like this:

MODE=(
     MODE_NAME=MYMODE
     AUTO_ACT=0
     COMPRESSION=PROHIBITED
     COS_NAME=#INTER
     CRYPTOGRAPHY=NONE
     DEFAULT_RU_SIZE=1
     MAX_NEGOTIABLE_SESSION_LIMIT=128
     MAX_RU_SIZE_UPPER_BOUND=4096
     MIN_CONWINNERS_SOURCE=15
     PLU_MODE_SESSION_LIMIT=32
     RECEIVE_PACING_WINDOW=1
)

Modifying a Keyword in a Template File

When using the update file to modify an existing keyword definition, the original keyword should exist in the template file. If it does not exist in the template file, the update file adds an entry to the new configuration. You must specify the key parameter in the update file to identify the target keyword. Only those parameters specified in the update file keyword are updated in the template file's keyword. Parameters not specified in the update file are left unchanged. For example, if the following MODE keyword is in the template file:

MODE=(
     MODE_NAME=#INTER
     AUTO_ACT=0
     COMPRESSION=PROHIBITED
     COS_NAME=#INTER
     CRYPTOGRAPHY=NONE
     DEFAULT_RU_SIZE=1
     MAX_NEGOTIABLE_SESSION_LIMIT=256
     MAX_RU_SIZE_UPPER_BOUND=4096
     MIN_CONWINNERS_SOURCE=128
     PLU_MODE_SESSION_LIMIT=256
     RECEIVE_PACING_WINDOW=20
)

and the following keyword is specified in the update file:

MODE=(
     MODE_NAME=#INTER
     AUTO_ACT=10
)

the resulting configuration would have the following MODE keyword definition:

MODE=(
     MODE_NAME=#INTER
     AUTO_ACT=10
     COMPRESSION=PROHIBITED
     COS_NAME=#INTER
     CRYPTOGRAPHY=NONE
     DEFAULT_RU_SIZE=1
     MAX_NEGOTIABLE_SESSION_LIMIT=256
     MAX_RU_SIZE_UPPER_BOUND=4096
     MIN_CONWINNERS_SOURCE=128
     PLU_MODE_SESSION_LIMIT=256
     RECEIVE_PACING_WINDOW=20
)

Deleting a Keyword from a Template File

When using the update file to delete a keyword from the template, you must specify the key parameter and value that identify the keyword, along with the keyword DELETE. For example, if the template file specifies the following keyword:

MODE=(
     MODE_NAME=#INTER
     AUTO_ACT=0
     COMPRESSION=PROHIBITED
     COS_NAME=#INTER
     CRYPTOGRAPHY=NONE
     DEFAULT_RU_SIZE=1
     MAX_NEGOTIABLE_SESSION_LIMIT=256
     MAX_RU_SIZE_UPPER_BOUND=4096
     MIN_CONWINNERS_SOURCE=128
     PLU_MODE_SESSION_LIMIT=256
     RECEIVE_PACING_WINDOW=20
)

and the response file contains the following keyword:

MODE=(
     MODE_NAME=#INTER
     DELETE
)

the resulting configuration does not contain the #INTER mode definition.

The DELETE keyword can appear after a parameter=value specification or on a line by itself, either preceding or following the parameter. For example, the following uses of the DELETE keyword are valid:

MODE=(
     MODE_NAME=#INTER
     DELETE
)
MODE=(
     DELETE
     MODE_NAME=#INTER
)

The DELETE keyword cannot appear in front of a parameter=value specification on the same line. For example, the following uses of the DELETE keyword are not valid:

MODE=(
     DELETE MODE_NAME=#INTER
)
 
MODE=(
     MODE_NAME=#INTER DELETE
)

To delete all keywords of a particular type, or to delete one keyword that does not have a key field, only the keyword and the DELETE keyword are necessary. For example,

MODE=(
     DELETE
)

Automatic Device Name Generation (5250 Only)

The Telnet 5250 client function can generate a new and non-arbitrary DEVice NAME (DEVNAME) for a session without requiring per-session profile (.WS) customization or a user exit.

You can use keywords and special characters in the WorkStationID (WID) field (in the [5250] stanza of the Workstation profile) to cause some or all of the following information to be substituted into the DEVice NAME value that is sent to the TN5250 server:

When specified, the Collision Avoidance ID enables the generation of a new DEVice NAME if the Telnet server rejects a submitted name (which can occur when the old name is already in use on the iSeries®, eServer™ i5, or System i5®). The ability to have a variety of names generated allows multiple sessions to the same iSeries, eServer i5, or System i5 from one or more clients using just one WorkStation Profile (.WS) file. The definition of the existing .WS file parameter WorkStationID in the [5250] stanza is extended to accomplish this.

Substitution Characters

You can use special substitution characters in the WID field to control the placement of the generated information into the DEVNAME field. One substitution character is used in the WID for each generated character. This reserves space in the DEVNAME for each generated character and indicates where each generated character is to be placed. The three special substitution characters are:

Short Session ID
(value range: A-Z or a-z) The special character signifying this in the WID is the asterisk (*).
Example:
If the WorkstationID is configured as 123* and the short ID of the first session is A, then the device names generated for the first three sessions will be 123A, 123B, and 123C.
Session Type ID
(possible values: S for diSplay or P for Printer) The special character signifying this in the WID is the percent sign (%).
Example:
If the Workstation ID is configured as %123* and the session type is Printer, then the first three device names generated would be P123A, P123B, and P123C.
Collision Avoidance ID
(value range: 1-9, A-Z or a-z) The Collision Avoidance ID (CAID) is used by the device name collision (DNC) function (see Device Name Collision Processing) to generate a new DEVice NAME when the old name is rejected by the Telnet server as already being in use. The special character signifying this in the WID is the equals sign (=).
Example:
If the Workstation ID is configured as %ABC=, the session type is Display, and the device name SABC1 is already in use on the iSeries, eServer i5, or System i5, then the first generated device name (SABC1) will be rejected by the server, but the second name (SABC2) will be accepted.

Client Naming Function

If you specify a Client Naming (CN) substitution keyword in the Workstation ID (WID) field, then an external name is retrieved and used when generating the DEVice NAME.

The CN keywords are prefixed with the ampersand character (&), followed by a five character identifier. Two keywords are supported:

&COMPN
Windows COMPuter Name for the client
&USERN
USER Name specified during logon to the Windows computer where the emulator executes

A name whose length exceeds the space remaining in the 10 character long DEVNAME field will have that excess trimmed from the left side by default. Excess characters can alternatively be trimmed from the right side by prefixing the CN keyword with a plus sign (+) character (for example, +&COMPN).

Notes:
  1. If the specified name cannot be obtained, then the message Unable to get the local "x" name (where "x" is COMPN or USERN) is displayed in the status bar.
  2. If a client naming keyword is specified in the WID, then characters other than those defined for this feature are ignored.
  3. A numeric character in the first position of a DEVNAME is invalid, and may be converted by the iSeries, eServer i5, or System i5 to the pound (or number) character (#).
Example A:
If the Workstation ID is &COMPN* and the name of the local computer is clientaccess1, then the device names generated for the first three sessions would be ntaccess1A, ntaccess1B, and ntaccess1C.
Example B:
If the Workstation ID is +&COMPN*% and the name of the USER logon for the local computer is clientaccess1, then the device names generated for the first three sessions would be clientaccA, clientaccB, and clientaccC.

Device Name Collision Processing

Device name collision occurs when a Telnet client sends the Telnet server a virtual device name, but that device name is already in use on the server. When this occurs, the Telnet server sends a request to the client asking it to send a different DEVNAME.

Device name collision (DNC) processing handles requests from the server for a different DEVNAME. If the collision avoidance ID (CAID) substitution character is present in the WID, the CAID is incremented and sent as part of the new DEVNAME to the server.

If the server requests a different DEVNAME and the CAID is not present in the WID, then the error message Device Name "x" is invalid or already in use on the server is displayed on the status bar and the session is disconnected.

Commands for Emulator Functions

Z and I Emulator for Windows provides the following commands for managing Z and I Emulator for Windows sessions:

PCOMSTRT
Start a Z and I Emulator for Windows session
PCOMSTOP
Stop a Z and I Emulator for Windows session
PCOMQRY
Query Z and I Emulator for Windows sessions

Start a Z and I Emulator for Windows Session

The command PCOMSTRT has the following parameters:

/p
Name of workstation profile to start (required). The syntax is /p=workstation-profile. You can specify the workstation profile as either the path (drive, directory, and file name) or just the file name, in which case the location of the workstation profile file is the user-class application data directory.
Note:
If multiple /p parameters are given, PCOMSTRT only uses the last one to start a profile (.WS file).
/s
Session letter of the session to start. The syntax is /s=session-letter. This is optional. If omitted, the first available session letter is used.
/w
Session window startup state. The syntax is /w={0|1|2|3}.
0
Hidden
1
Normal (default)
2
Minimized
3
Maximized
/q
Quiet mode. In quiet mode, PCOMSTRT does not write any messages to stdout.
/nowait
Do not wait for session to start. The /nowait option tells PCOMSTRT to complete execution without waiting until the emulator session is started. There is no /wait option; the default is to wait until the session is started.
/?
Displays help information.

Returns: DOS Error level is set for use when this command is invoked by a program. When the command is directly entered, a message indicating the session is starting is displayed.

Stop a Z and I Emulator for Windows Session

The command PCOMSTOP has the following parameters:

/s
Session letter of session to stop. The syntax is /s=session-letter. This is optional. If omitted, the first available session letter is used.
/all
Stops all sessions
/NCE
Stops all or specific session without confirmation, even if the confirmation on exit or exit all option are set.
/q
Quiet mode. In quiet mode, PCOMSTOP does not write any messages to stdout.
/?
Displays help information.

Returns: DOS Error level is set for use when this command is invoked by a program. When the command is directly entered, a message is displayed indicating the session is stopping.

Query Z and I Emulator for Windows Sessions

The command PCOMQRY has the following parameters:

/s
Session letter of session to query, The syntax is /s=session-letter. This is optional. If omitted, the first available session letter is used.
/all
Queries all sessions.
/q
Quiet mode. In quiet mode, PCOMQRY does not write any messages to stdout.
/nowait
Do not wait for session to query. The /nowait option tells PCOMQRY to complete execution without waiting until the emulator session is queried. There is no /wait option; the default is to wait until the session is queried.
/?
Displays help information.