Preparing to Use the Virtual Terminal APIs

The following steps are required to prepare your System i^® platform to run an application using the virtual terminal APIs:

Set the number of automatically created virtual terminals using the Automatic virtual device configuration indicator (QAUTOVRT) system value
Set the Limit security officer device access (QLMTSECOFR) system value
Create user profiles using the Create User Profile (CRTUSRPRF) command

Step 1: Setting the Number of Automatically Created Virtual Terminals

The IBM^® i operating system uses virtual terminals to allow a server program to interact with its client by sending and receiving data with IBM i applications. The operating system will automatically select (and create if necessary) these virtual terminals for you.

The QAUTOVRT system value specifies the maximum number of terminals that will be automatically configured by the system. When you set the QAUTOVRT system value, the operating system automatically configures the required virtual controllers and terminals. Controllers coordinate and control the operation of one or more input/output terminals (such as workstations) and synchronize the operation of such terminals with the operation of the entire system. Use the Change System Value (CHGSYSVAL) command to change the value of the QAUTOVRT system value. For example, entering the following command string changes the number of virtual terminals that can be allocated on a system to 50:

CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(50)

To determine and set the maximum number of users you want signed on to the system at any time, do the following:

Set the QAUTOVRT system value to *NOMAX, the maximum value allowed.
Have your users use the system until you decide that the number of virtual terminals created is sufficient for normal system operation.
Use the Work with Configuration Status (WRKCFGSTS) command to determine the number of workstations configured.
Change the QAUTOVRT system value from *NOMAX to the number of virtual terminals you require for normal operation.

If you have never allowed virtual terminals to be configured automatically on your system, the QAUTOVRT system value is 0. As a result, you cannot use the virtual terminal APIs because the operating system is not able to create more workstations than the number specified. If you change the QAUTOVRT system value to 10, the next virtual terminal path opened causes the operating system to create a virtual terminal. This virtual terminal is created because the number of virtual terminals on the controller (0) is less than the number specified in the QAUTOVRT system value (10). Even if you change the specified number to 0 again, the next virtual terminal opened may succeed if a virtual terminal exists that is not being used.

If a virtual terminal does not exist or is in use, the operating system does not create a new virtual terminal because the number of virtual terminals currently existing is greater than or equal to the specified QAUTOVRT system value. When the number of virtual terminals that currently exist is greater than or equal to the QAUTOVRT system value, the message CPF8940, "Cannot automatically select virtual device", is sent to the system operator message queue (QSYSOPR). You must either try again when a virtual terminal description becomes available or increase the QAUTOVRT system value.

The operating system uses the following conventions for naming virtual controllers and workstations:

Virtual controllers named QPACTLnn are used for auto-created virtual terminal descriptions.
Virtual controllers named QVIRCDnnnn are used for named virtual terminal descriptions.
Virtual terminal descriptions named QPADEVxxxx are auto-created devices.
Named virtual terminal devices may be requested using the virtual terminal APIs. An example of a named virtual terminal device would be NEWYORK001.

Consider the following when you allow the operating system to automatically configure workstations:

The operating system does not delete virtual terminals, even when the number of workstations attached to virtual controllers exceeds the limit set by QAUTOVRT.
If you want the extra workstations deleted, you must manually delete them.
The operating system allows a maximum of 254 virtual terminals on the QPACTL01 controller before it creates QPACTL02. This value is usually adequate. If you delete workstations to enforce a smaller value for the QAUTOVRT limit, begin by deleting the workstations from the controller with the highest numeric value in its name (where nn in the QPACTLnn name is largest).
Note: Changing this system value affects other products and programs that require automatic configuration. This includes TCP/IP TELNET, 5250 display station pass-through, and any other programs using the virtual terminal APIs.

Step 2: Setting the Limit Security Officer (QLMTSECOFR) Value

The Limit security officer device access (QLMTSECOFR) system value, limits the devices the security officer can sign on to. The security officer controls all of the security authorizations provided by the system. If the QLMTSECOFR value is greater than zero, the security officer must be authorized to use the virtual device descriptions. When this value equals 0, however, the system does not limit the devices the security officer can use to sign on the system.

When the system security level (QSECURITY) system value is set to 30, a security officer with all object authority (*ALLOBJ) must be authorized to use the workstations. For example, for each display station that a security officer wants to sign on to (local, remote, or virtual), the user must authorize the security officer using the following Grant Object Authority (GRTOBJAUT) command:

GRTOBJAUT OBJ(display-name) OBJTYPE(*DEVD) AUT(*CHANGE) USER(QSECOFR)

This procedure is very important because using the virtual terminal APIs automatically configures virtual terminals (devices). Automatic configuration is a function that names and creates the descriptions of network devices and controllers attached to a line. If the QLMTSECOFR value is set to 0, all virtual terminals automatically configured when you use the virtual terminal APIs can be used by the security officer. If you set the QLMTSECOFR value to 1, your security officer is not able to use the virtual terminals unless you specifically grant object authority to the security officer for that virtual terminal. The automatic configuration support can delete and re-create the virtual terminal. If this occurs, authority must be granted to the security officer each time the virtual terminal is created.

Security Considerations

The number of sign-on attempts allowed increases if virtual terminals are automatically configured. The number of sign-on attempts is equal to the number of system sign-on attempts allowed multiplied by the number of virtual terminals that can be created. The number of system sign-on attempts allowed is defined by the QMAXSIGN system value. The number of virtual terminals that can be created is defined by the QAUTOVRT system value.

Step 3: Creating User Profiles

You should create one or more user profiles on the system for users of the virtual terminal supported by the client and server programs. The default user profile is *SYS. The following example shows a sample user profile:

CRTUSRPRF  USRPRF(CLERK1)  PASSWORD(unique-password)
           JOBD(CLERKLIB/CLERKL1)
           TEXT('User profile for one group of clerks')

[ Back to top | >Virtual Terminal APIs | APIs by category ]