I/O Communications Buffers

I/O Communications Buffers

For uniformity, throughout the AIM user interface, a standard data format is employed to pass input, command, and status information. That is, this data format, which is called an I/O communications buffer, is used to represent the following:

Key-press commands received from the operator.
Commands generated as a result of selecting a pulldown menu item.
Commands generated by spawn routines to pass new instructions back to the menu driver.
Status information returned at the completion of the menu driver and other operator-interface routines.

General Format

I/O communications buffers are implemented as V+ strings, the contents of which are organized into a series of fields. The first fields contain (header) data that are stored in a fixed format (see below). These fields define the destination system, source system, function, and qualifier. The source and destination fields (which are currently unused) are for use during network operations. The function code specifies that the buffer contains a user-interface message, and the qualifier defines the type of message.

The header section is followed by a variable-format data section. The format of the data section is a function of the type of message. For simple messages, the data section is unused. For more complicated messages, the data section may contain any combination of numeric and text information.

There are two general types of formats for I/O buffers: command, and status information. All commands contain a positive value for the qualifier, and have a variable-format data section. All status messages have a zero or negative qualifier, and contain a single variable-length text string in the data field. For error messages, the negative qualifier corresponds to a V+ or AIM error code, and the text string contains an optional message that further defines the source or cause of the error. A zero qualifier value for a status message indicates success.

The general format of the fields in an I/O buffer is described in Format of I/O Communications Buffer. The first column of the table lists the V+ variables that can be used to specify the offset to the start of each field. The second column indicates the type of data stored in each field (for example, 16-bit integer number [$INTB], 8-bit byte [$CHR], or ASCII text). The last column describes the contents of the fields.

Table 9-1. Format of I/O Communications Buffer

V+ Variable for Field Offset

Data Type

Data Field Contents

io.hdr.dsa (1)

$INTB

Destination system address (normally 0)

io.hdr.did (3)

$CHR

Destination queue ID (normally 0)

io.hdr.ssa (4)

$INTB

Source system address (normally 0)

io.hdr.sid (6)

$CHR

Source queue ID (normally 0)

io.fun (7)

$INTB

Function code (1 for menu messages)

io.qal (9)

$INTB

Function qualifier

io.dat (11)

ASCII

Optional variable-format data section (maximum length of 118 bytes)

As a convenience for defining I/O buffer values, the following string constants are defined by AIM:
	$io.cmd.hdr = $INTB(0)+$CHR(0)+$INTB(0)+$CHR(0)+$INTB(1) 
	$io.cmd.nop = $INTB(0)+$CHR(0)+$INTB(0)+$CHR(0)+$INTB(1)+$INTB(0)
 
In the following sections, each of the command messages is described, along with the format for its variable-data field. For each command, the name of the V+ variable (ky.*) whose value corresponds to the I/O buffer qualifier is presented, followed by a brief description of the command. In certain instances, additional I/O buffer offset variables (io.*) are defined to simplify the creation and decoding of the I/O buffer data field.

Window Events

I/O Buffer Qualifiers for Window Events lists the window events that are fielded by the menu driver and passed in I/O buffers. Each of these commands corresponds to an input event that can be generated by V+. (These commands are not normally generated by user routines.) You can refer to the V+ Operating System Reference Guide for more information on the interpretation of these events and their parameters.

Table 9-2. I/O Buffer Qualifiers for Window Events

I/O Buffer Qualifier

Window Event

ky.but.down

Mouse button-down event

ky.but.up

Mouse button-up event

ky.dbl.clk

Mouse button double click

ky.but.move

Mouse move with button down

ky.win.sel

Window selected

ky.win.nsel

Window deselected

ky.sld.str

Slide-bar start event

ky.sld.mve

Slide-bar move event

ky.sld.end

Slide-bar up event

ky.pull.down

Pulldown menu event

ky.cls.win

Window-closed event

For the commands listed in I/O Buffer Qualifiers for Window Events, the data field of the I/O buffer contains the parameters returned by the V+ GETEVENT instruction. These parameters are formatted as shown in Format of I/O Buffer Data Field for Window Events.

Table 9-3. Format of I/O Buffer Data Field for Window Events

V+ Variable for Field Offset

Data Type

Data Field Contents

io.int1 (11)

$INTB

Window event: first integer argument

io.int2 (13)

$INTB

Window event: second integer argument

io.int3 (15)

$INTB

Window event: third integer argument

Menu Commands Without Parameters

The commands listed in I/O Buffer Qualifiers for Menu Commands Without Parameters do not use the variable data field of the I/O buffer. In general, these commands can be generated from any source.

Table 9-4. I/O Buffer Qualifiers for Menu Commands Without Parameters

I/O Buffer Qualifier

Action of Menu Driver

ky.right

Move cursor right in field

ky.left

Move cursor left in field

ky.up

Move cursor up in field

ky.down

Move cursor down in field

ky.f.right

Move right to next active field

ky.f.left

Move left to next active field

ky.f.up

Move up to next active field

ky.f.down

Move down to next active field

ky.tab

Move to next active field

ky.b.tab

Move to previous active field

ky.previous

Go to previous record of primary database

ky.next

Go to next record of primary database

ky.first

Go to first record of primary database

ky.last

Go to last record of primary database

ky.undo

Undo changes to field

ky.insert

Insert a new line

ky.delete

Delete a character

ky.delete.l

Delete a line or field

ky.search

Initiate search operation

ky.change

Initiate change operation

ky.repeat

Repeat last search operation

ky.s.repeat

Repeat last change operation

ky.new

Create a new record

ky.copy.rec

Copy displayed record

ky.cut.rec

Cut displayed record

ky.paste.rec

Paste record

ky.paste.all

Paste all records

ky.goto

Display database record pointed to by field

ky.back

Return to previous database

ky.retrieve

Return record name to previous record

ky.display

Display index of possible record names

ky.index

Display record index of the current database

ky.teach

Initiate teaching of field value

ky.redraw

Redraw current menu page

ky.refresh

Update all auto-refresh fields

ky.exit

Exit current menu

ky.exit.2
ky.exit.3
ky.exit.4
ky.no
ky.do.it
ky.okay
ky.yes These commands, which are all interpreted the same as "ky.exit" by the menu driver, are used to distinguish between different exit conditions.

ky.s.exit Exit all nested menus

ky.help Display help for current field

ky.s.help Display help for current page

ky.save Save all changed database values

ky.halt Halt current operation

ky.shutdown Shutdown AIM system

Commands for Displaying a Menu Page

The commands listed in I/O Buffer Qualifiers for Menu Commands to Display Menu Pages display a new menu page. Although these commands can be returned by a button spawn routine to initiate the display of a new menu, displaying a menu page is normally performed by directly executing the menu driver from the spawn routine. These command formats are used by the pulldown menus to invoke menu display commands. In most cases, the routine mu.set.goto() can be used to build the command. This routine takes care of all the low-level details of packing the command buffers.

Table 9-5. I/O Buffer Qualifiers for Menu Commands to Display Menu Pages

I/O Buffer Qualifier

Action of Menu Driver

ky.menu

Create a new window whose parent is the window currently displayed, and display the specified menu page in the new window. When the new menu page terminates execution, control returns to the menu page previously displayed.

ky.m.menu

Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, create a new window, and display the contents of the menu page in the new "main" window.

For the commands listed in I/O Buffer Qualifiers for Menu Commands to Display Menu Pages, the data section of the I/O buffer contains the information listed in Format of I/O Buffer Data Field for Page-Display Commands.

Table 9-6. Format of I/O Buffer Data Field for Page-Display Commands

V+ Variable for Field Offset

Data Type

Data Field Contents

io.ms.mode

$CHR

Mode of operation. All modes perform the basic operation of displaying a specified menu page. In addition, the mode indicates that one of the following actions is to be taken:

MODE INTERPRETATION

0 This is the standard menu command.

1 This menu command is generated as a result of a GOTO command. When the menu driver receives this command, it saves away information so that a subsequent BACK or RETRIEVE command can return to the menu page that generated the GOTO.

2 This command is generated by the menu driver when it receives a BACK command and the previous operation was a GOTO menu operation. The menu driver generates this command to restart execution of the menu page that processed the GOTO.

3 This command is generated by the menu driver when it receives a RETRIEVE command and the previous operation was a GOTO menu operation. The menu driver generates this command to restart execution of the menu page that processed the GOTO and to pass back the name of the record that was RETRIEVED.

4 This is like mode 1 except a new record is created.

io.ms.name

ASCII

15-character string that specifies the name of the menu page to be displayed. If the name is shorter than 15 characters, it must be padded with trailing NUL [i.e., $CHR(0)] characters.

io.ms.file

ASCII

12-character string that specifies the name of the menu file that contains the required menu page. If the name has less than 15 characters, it must be padded with trailing NUL characters.

io.ms.db.ty

$INTB

Type of the primary database associated with the menu page. If <0, the absolute value is the type of a global database.

io.ms.rec

$INTB

Number of the first record of the primary database to be displayed, or 0 if the record currently opened is to be displayed.

io.ms.acc

$CHR

Required user access level for displaying the menu page (0 to 7).

io.ms.norun

$CHR

Non-zero if the menu page cannot be displayed while a sequence if running.

io.ms.r.ty

$CHR

For mode 1, 2, 3, or 4: Type of the database that contains the value to be filled in if a RETRIEVE is performed. If <0, the absolute value is the type of a global database.

io.ms.r.rec

$INTB

For mode 1, 2, 3, or 4: Number of the record that contains the value to be filled in if a RETRIEVE is performed.

io.ms.r.fld

$CHR

For mode 1, 2, 3, or 4: Number of the field to be filled in by the RETRIEVE operation.

io.ms.r.idx

$CHR

For mode 1, 2, 3, or 4: Number of the index of the field to be filled in by RETRIEVE.

io.ms.r.val

ASCII

For mode 3: 15-character string that contains the name of the record that is being RETRIEVED. If the name is shorter than 15 characters, it must be padded with trailing NUL characters.

Commands for Executing a Sequence or Spawning a V+ Routine

The commands listed in I/O Buffer Qualifiers for Menu Commands to Execute V+ Spawn Routines or a Sequence execute a user spawn routine. These commands are generated almost exclusively by the pulldown menu routines. In most cases, the routine mu.set.goto() can be used to build the command. This routine takes care of all the low-level details of packing the command buffers.

Table 9-7. I/O Buffer Qualifiers for Menu Commands to Execute V+ Spawn Routines or a Sequence

I/O Buffer Qualifier

Action of Menu Driver

ky.spawn

Suspend execution of the current menu page and execute the specified spawn routine. When the spawn routine terminates execution, control returns to the suspended menu page (subject to any new command returned by the spawn routine).

ky.m.spawn

Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, and then begin execution of the specified "main" spawn routine.

ky.seq

Suspend execution of the current menu page and call a control sequence. When the control sequence terminates execution, control returns to the suspended menu page.

ky.m.seq

Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, and then begin execution of the specified "main" control sequence.

For the commands listed in I/O Buffer Qualifiers for Menu Commands to Execute V+ Spawn Routines or a Sequence, the data section of the I/O buffer contains the information listed in Format of I/O Buffer Data Field for Spawn Commands.

Table 9-8. Format of I/O Buffer Data Field for Spawn Commands

V+ Variable for Field Offset

Data Type

Data Field Contents

io.ms.mode

$CHR

Mode of operation. All modes perform the basic operation of executing a specified spawn routine. In addition, the mode indicates that one of the following actions is to be taken:
MODE INTERPRETATION

0 This is the standard menu command.

1 This spawn command is generated as a result of a GOTO command. When the menu driver receives this command, it saves information so that a subsequent BACK or RETRIEVE command can return to the menu page that generated the GOTO.

2 This command is generated by the menu driver when it receives a BACK command and the previous operation was a GOTO. The menu driver generates this command to restart execution of the spawn routine that processed the GOTO.

3 This command is generated by the menu driver when it receives a RETRIEVE command and the previous operation was a GOTO. The menu driver generates this command to restart execution of the spawn routine that processed the GOTO and to pass back the name of the record that was RETRIEVED.

4 This is like mode 1 except a new record is created.

io.ms.name

ASCII

15-character string that specifies the name of the V+ routine or sequence to be executed. If the name is shorter than 15 characters, it must be padded with trailing NUL [i.e., $CHR(0)] characters.

io.ms.file

ASCII

12-character string that contains the optional name of an "overlay" file or resource module that contains the spawn routine. The overlay file or resource module is automatically loaded into memory (if required), before the spawn routine is executed. The overlay file or resource module will be deleted from memory when the memory space is later required by another spawn routine. If the name is shorter than 15 characters, it must be padded with trailing NUL characters.

io.ms.db.p

$INTB

Type of the primary database that is passed to the spawn routine. If <0, the absolute value is the type of a global database.

io.ms.rec

$INTB

Value of the "spawn routine argument" that is passed to the spawn routine.

io.ms.acc

$CHR

Required user access level for displaying the menu page (0 to 7).

io.ms.norun

$CHR

Nonzero if the menu page cannot be displayed while a sequence if running.

io.ms.r.ty

$CHR

For mode 1, 2, 3, or 4: Type of the database that contains the value to be filled in if a RETRIEVE is performed. If <0, the absolute value is the type of a global database.

io.ms.r.rec

$INTB

For mode 1, 2,3, or 4: Number of the record that contains the value to be filled in if a RETRIEVE is performed.

io.ms.r.fld

$CHR

For mode 1, 2, 3, or 4: Number of the field to be filled in by the RETRIEVE operation.

io.ms.r.idx

$CHR

For mode 1, 2, 3, or 4: Number of the index of the field to be filled in by RETRIEVE.

io.ms.r.val

ASCII

For mode 3: 15-character string that contains the name of the record that is being RETRIEVED. If the name is shorter than 15 characters, it must be padded with trailing NUL characters.

V+ Variable for Field Offset	Data Type	Data Field Contents
io.hdr.dsa (1)	$INTB	Destination system address (normally 0)
io.hdr.did (3)	$CHR	Destination queue ID (normally 0)
io.hdr.ssa (4)	$INTB	Source system address (normally 0)
io.hdr.sid (6)	$CHR	Source queue ID (normally 0)
io.fun (7)	$INTB	Function code (1 for menu messages)
io.qal (9)	$INTB	Function qualifier
io.dat (11)	ASCII	Optional variable-format data section (maximum length of 118 bytes)

I/O Buffer Qualifier	Window Event
ky.but.down	Mouse button-down event
ky.but.up	Mouse button-up event
ky.dbl.clk	Mouse button double click
ky.but.move	Mouse move with button down
ky.win.sel	Window selected
ky.win.nsel	Window deselected
ky.sld.str	Slide-bar start event
ky.sld.mve	Slide-bar move event
ky.sld.end	Slide-bar up event
ky.pull.down	Pulldown menu event
ky.cls.win	Window-closed event

V+ Variable for Field Offset	Data Type	Data Field Contents
io.int1 (11)	$INTB	Window event: first integer argument
io.int2 (13)	$INTB	Window event: second integer argument
io.int3 (15)	$INTB	Window event: third integer argument

I/O Buffer Qualifier	Action of Menu Driver
ky.right	Move cursor right in field
ky.left	Move cursor left in field
ky.up	Move cursor up in field
ky.down	Move cursor down in field
ky.f.right	Move right to next active field
ky.f.left	Move left to next active field
ky.f.up	Move up to next active field
ky.f.down	Move down to next active field
ky.tab	Move to next active field
ky.b.tab	Move to previous active field
ky.previous	Go to previous record of primary database
ky.next	Go to next record of primary database
ky.first	Go to first record of primary database
ky.last	Go to last record of primary database
ky.undo	Undo changes to field
ky.insert	Insert a new line
ky.delete	Delete a character
ky.delete.l	Delete a line or field
ky.search	Initiate search operation
ky.change	Initiate change operation
ky.repeat	Repeat last search operation
ky.s.repeat	Repeat last change operation
ky.new	Create a new record
ky.copy.rec	Copy displayed record
ky.cut.rec	Cut displayed record
ky.paste.rec	Paste record
ky.paste.all	Paste all records
ky.goto	Display database record pointed to by field
ky.back	Return to previous database
ky.retrieve	Return record name to previous record
ky.display	Display index of possible record names
ky.index	Display record index of the current database
ky.teach	Initiate teaching of field value
ky.redraw	Redraw current menu page
ky.refresh	Update all auto-refresh fields
ky.exit	Exit current menu
ky.exit.2 ky.exit.3 ky.exit.4 ky.no ky.do.it ky.okay ky.yes	These commands, which are all interpreted the same as "ky.exit" by the menu driver, are used to distinguish between different exit conditions.
ky.s.exit	Exit all nested menus
ky.help	Display help for current field
ky.s.help	Display help for current page
ky.save	Save all changed database values
ky.halt	Halt current operation
ky.shutdown	Shutdown AIM system

I/O Buffer Qualifier	Action of Menu Driver
ky.menu	Create a new window whose parent is the window currently displayed, and display the specified menu page in the new window. When the new menu page terminates execution, control returns to the menu page previously displayed.
ky.m.menu	Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, create a new window, and display the contents of the menu page in the new "main" window.

V+ Variable for Field Offset	Data Type	Data Field Contents
io.ms.mode	$CHR	Mode of operation. All modes perform the basic operation of displaying a specified menu page. In addition, the mode indicates that one of the following actions is to be taken: MODE INTERPRETATION 0 This is the standard menu command. 1 This menu command is generated as a result of a GOTO command. When the menu driver receives this command, it saves away information so that a subsequent BACK or RETRIEVE command can return to the menu page that generated the GOTO. 2 This command is generated by the menu driver when it receives a BACK command and the previous operation was a GOTO menu operation. The menu driver generates this command to restart execution of the menu page that processed the GOTO. 3 This command is generated by the menu driver when it receives a RETRIEVE command and the previous operation was a GOTO menu operation. The menu driver generates this command to restart execution of the menu page that processed the GOTO and to pass back the name of the record that was RETRIEVED. 4 This is like mode 1 except a new record is created.
io.ms.name	ASCII	15-character string that specifies the name of the menu page to be displayed. If the name is shorter than 15 characters, it must be padded with trailing NUL [i.e., $CHR(0)] characters.
io.ms.file	ASCII	12-character string that specifies the name of the menu file that contains the required menu page. If the name has less than 15 characters, it must be padded with trailing NUL characters.
io.ms.db.ty	$INTB	Type of the primary database associated with the menu page. If <0, the absolute value is the type of a global database.
io.ms.rec	$INTB	Number of the first record of the primary database to be displayed, or 0 if the record currently opened is to be displayed.
io.ms.acc	$CHR	Required user access level for displaying the menu page (0 to 7).
io.ms.norun	$CHR	Non-zero if the menu page cannot be displayed while a sequence if running.
io.ms.r.ty	$CHR	For mode 1, 2, 3, or 4: Type of the database that contains the value to be filled in if a RETRIEVE is performed. If <0, the absolute value is the type of a global database.
io.ms.r.rec	$INTB	For mode 1, 2, 3, or 4: Number of the record that contains the value to be filled in if a RETRIEVE is performed.
io.ms.r.fld	$CHR	For mode 1, 2, 3, or 4: Number of the field to be filled in by the RETRIEVE operation.
io.ms.r.idx	$CHR	For mode 1, 2, 3, or 4: Number of the index of the field to be filled in by RETRIEVE.
io.ms.r.val	ASCII	For mode 3: 15-character string that contains the name of the record that is being RETRIEVED. If the name is shorter than 15 characters, it must be padded with trailing NUL characters.

I/O Buffer Qualifier	Action of Menu Driver
ky.spawn	Suspend execution of the current menu page and execute the specified spawn routine. When the spawn routine terminates execution, control returns to the suspended menu page (subject to any new command returned by the spawn routine).
ky.m.spawn	Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, and then begin execution of the specified "main" spawn routine.
ky.seq	Suspend execution of the current menu page and call a control sequence. When the control sequence terminates execution, control returns to the suspended menu page.
ky.m.seq	Perform the equivalent of SHIFT + EXIT (SHIFT+F4): terminate processing of any current menus, and then begin execution of the specified "main" control sequence.