The virtual terminal APIs allow your AS/400 application programs to interact with AS/400 application programs that are performing work station input and output (I/O).
A virtual terminal is a device that does not have hardware associated with it. It forms a connection between your application and AS/400 applications, representing a physical work station (possibly on a remote system). The OS/400 licensed program manages the virtual terminal, which directs work station I/O performed by an AS/400 application to the virtual terminal. The virtual terminal APIs allow another AS/400 application, called a server program, to work with the data associated with the virtual terminal.
In a distributed systems environment, the requesting program is called a client; the answering program is called a server. The client and server programs may reside on the same AS/400 system or may be distributed between two different systems. The server program generally runs on behalf of (or in conjunction with) the client program. Together, the server program and the client program allow a work station to be supported as if the work station were connected locally.
provides the virtual terminal APIs, including syntax, parameters, notes about usage, and associated AS/400 system messages. contains an example of how the OS/400 operating system, the server program, the client program, and the work station device interact when processing a system request.
This section includes:
Figure 1 shows a model for a distributed systems environment between an IBM PS/2 work station and an AS/400 system. The client program resides on the PS/2 work station, while the server program resides on the AS/400 system. This model is similar to the way the AS/400 supports a Client Access work station function.
Figure 1. Example Virtual Terminal Client/Server Model
The client program running on the PS/2 work station shown in Figure 1 does the following:
The link between the client program and server program uses DOS and OS/400 communications support. This may be LU 6.2, TCP/IP, or some other communications protocol.
You can write a server application program in any AS/400-supported high-level language (HLL), such as the ILE C programming language. The server program provides work station support for the AS/400 system acting as the server. The virtual terminal APIs allow a server program to read and write virtual terminal data. Virtual terminal data is always in a 5250 data stream format. See the IBM 5494 Functions Reference book, SC30-3533, for more information on 5250 data streams.
The virtual terminal APIs provide an interface between the server program and the virtual terminal supported by the OS/400 licensed program. The virtual terminal represents the OS/400 link between the server program and the AS/400 application and is managed entirely by the OS/400 licensed program.
The AS/400 application is a licensed program or a user-written application that performs a standard data transfer to a work station. This application can be written in any AS/400-supported HLL.
Several AS/400 jobs are involved when you use the virtual terminal APIs. The jobs can be classified into two groups:
The server program can be written to run in a single job or in more than one job, depending on the number of work stations to be supported per job. For example, you can support each work station using a single job by routing all requests from the work station client program to a particular server program job.
A server program should run in the same subsystem that other server programs are running. For controlling resource use, such as main storage, a separate subsystem for running all server programs is usually best. This is also advantageous for allowing performance tuning, such as the number of page faults. Generally, AS/400 applications run in subsystem QBASE.
If the subsystem under which you want the server program to run was created with the system defaults, you will not have to add a work station entry to the subsystem description. However, if you do need to add a work station entry to the subsystem description, you can use the Add Work Station Entry (ADDWSE) command.
Before a work station is allowed to sign-on, it must be defined to a subsystem. In this case, the work station is the virtual terminal device (QPADEVnnnn) automatically created by the OS/400 licensed program. The work station name, work station type, or *ALL must be specified in the subsystem description. Use the Display Subsystem Description (DSPSBSD) command to see the list of work station entries defined for a subsystem. The following command can be used to add all work station types to a subsystem named QBASE:
ADDWSE SBSD(QBASE) WRKSTNTYPE(*ALL)
For more information on automatically creating virtual terminals, see Step 1: Setting the Number of Automatically Created Virtual Terminals.
Note: The ADDWSE command is only valid when the subsystem description is not active.
You must specify a work station type when a virtual terminal device is opened. A server program can select several different types of work stations. See for a list of the types of work stations that are supported.
The OS/400 licensed program uses data queues to send data to the server program. The server program also uses data queues for interprocess communications with other AS/400 applications and API calls.
The data queue must exist before your application uses the virtual terminal APIs to open a path to a virtual terminal. See the CL Reference (Abridged) book for details about creating and deleting data queues. See for information on how a server program specifies the name of the data queue to be used.
The OS/400 licensed program communicates special events to the server program using the data queue. The AS/400 system provides the information about the special events using a data queue entry.
The following events result in data queue entries being sent:
Table 1 shows the structure of
OS/400 data queue
entries that are sent to the data queue when an application uses
the virtual terminal APIs. All data queue entries have the same
format.
Table 1. Format for OS/400 Data Queue Entries
| Name | Type | Description |
|---|---|---|
| Entry Type | CHAR(10) | Always set by OS/400 to *VRTTRM. |
| Entry ID | CHAR(2) | Entry ID associated with entry. Valid values for the 2
characters in this parameter are:
|
| VTHandle | CHAR(16) | The virtual terminal handle associated with the virtual terminal communications path previously opened by calling the Open Virtual Terminal Path (QTVOPNVT) API. See for additional details. |
|
| CHAR(52) | Reserved |
| Key | CHAR(*) |
Key value specified when the virtual terminal communications
path was opened. See for additional details
on specifying the key value. The key value can be used for
retrieving data queues by key.
|
The following steps are required to prepare your AS/400 system to run an application using the virtual terminal APIs:
The OS/400 licensed program uses virtual terminals to allow a server program to interact with its client by sending and receiving data with AS/400 applications. The OS/400 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 OS/400 licensed program automatically configures the required virtual controllers and terminals. Controllers coordinate and control the operation of one or more input/output terminals (such as work stations) 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 AS/400 system at any time, do the following:
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 OS/400 licensed program is not able to create more work stations than the number specified. If you change the QAUTOVRT system value to 10, the next virtual terminal path opened causes the OS/400 licensed program 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 OS/400 licensed program 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 OS/400 operating system uses the following conventions for naming virtual controllers and work stations:
If you want the extra work stations deleted, you must manually delete them.
Note: Changing this system value affects other AS/400 products and programs requiring automatic configuration. This includes TCP/IP TELNET, 5250 display station pass-through, and any other programs using the virtual terminal APIs.
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 AS/400 system. If the QLMTSECOFR value is greater than zero, the security officer must be authorized to use the virtual device descriptions. However, when this value equals 0, 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 work stations. 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.
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.
You should create one or more user profiles on the AS/400 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')
You can create your own virtual controllers and devices (terminals); however, you must use the same naming conventions as the automatic controller and device creation support. You may want to create the virtual terminal descriptions to control the number of sign-on attempts possible by not allowing automatic configuration of virtual terminals (which allows additional sign-on attempts to occur). See Security Considerations for additional information.
If you do not want to use automatically created descriptions, do the following:
CRTCTLVWS CTLD(QPACTL01)
TEXT('Virtual Controller for virtual terminals')
Note: You must use the OS/400 naming convention, QPACTLnn, for naming virtual controllers, where nn is a decimal number starting at 01.
CRTDEVDSP DEVD(QPADEV0001) DEVCLS(*VRT)
TYPE(5251) MODEL(11) CTL(QPACTL01)
TEXT('24 X 80 Monochrome
Display for Server Program')
After creating the descriptions, you must authorize the server program to use them. Use the Grant Object Authority (GRTOBJAUT) command to authorize the user profile used by the server program to the descriptions. This can be done using the following commands:
GRTOBJAUT OBJ(QPACTL01) OBJTYPE(*CTLD)
AUT(*CHANGE) USER(user-ID)
GRTOBJAUT OBJ(QPADEV0001) OBJTYPE(*DEVD)
AUT(*CHANGE) USER(user-ID)
You may want to prevent virtual terminals from being created automatically. To do this, set the QAUTOVRT system value to 0 as follows:
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(0)See Step 1: Setting the Number of Automatically Created Virtual Terminals for additional information.
Note: Changing this system value affects other AS/400 products and programs requiring automatic configuration. This includes TELNET, 5250 display station pass-through, and any other programs using the virtual terminal APIs.
When developing client and server programs using the virtual terminal APIs, you need to take the following items into consideration:
|
Top
| Virtual Terminal APIs Virtual Terminal Run-Time--Example | APIs by category |
| [Information Center Home Page | Feedback ] | [Legal | AS/400 Glossary] |