Menu Driver Application Notes
I/O Communications Buffer Format
The I/O Communications Buffers are implemented as V+ strings, the contents of which are organized into a series of data fields. As noted, the fields are broken down to header data and variable data. The header data is stored in a fixed format, which contains essentially system addressing, and function codes (see Format of I/O Communications Buffer).
The format of the data section is a function of the type of message or command that the menu driver is supposed to interpret. For simple status messages, the variable data fields are unused, however for complex commands, the data section may contain a combination of numeric and text information.
There are two general types of formats for the I/O buffers: command and status information. All commands contain a positive value for the "qualifier" field, and make use of the variable data section. All messages contain a zero or negative "qualifier" field and contain one variable length text string in the data field. By extracting the numeric code in the "qualifier field" the menu driver can determine if the remaining data in the buffer refers to a message or a command.
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 specifies the type of data stored in each field, and the last column describes the contents of the fields. NOTE: $INTB( ) data types are 16 bit integer numbers, and $CHR( ) data types are 8 bit bytes. The number in parenthesis next to each V+ Variable name in Table 1, represents the byte number at which the data specified begins.
I/O Buffer Layout illustrates the layout of the fields in the buffer. Each block represents 1 byte of data. The fields that contain $INTB( ) data types, for example, take up two bytes in the buffer, since the $INTB( ) function returns a 2-byte string containing the binary representation of a 16 bit integer.
The I/O communications buffer is built using V+ string commands keeping in mind the data type for each field. For example, as a convenience for defining I/O buffer values, there are two string constants that are defined in AIM: $io.cmd.hdr and $io.cmd.nop.
The string $io.cmd.hdr stands for "I/O Command Header". It is a standard string that defines all the necessary header information for the menu driver. It is built using the standard V+ string commands in the following manner:
$io.cmd.hdr = $INTB(0) + $CHR(0) + $INTB(0) + $CHR(0) + $INTB(1)
$io.cmd.hdr = "Destination System Address" + "Destination queue ID"+"Source System Address" + " Source Queue ID" + "Function Code"
In Format of I/O Communications Buffer, notice that the numeric values for the $INTB( ) and $CHR( ) functions in the $io.cmd.hdr definition above correspond to the values described in the Description portion of the table. This HEADER string MUST be included in ALL command and message strings passed to the menu driver!
Similarly, the string $io.cmd.nop, which stands for "I/O Command No Operation", is constructed in the same fashion:
$io.cmd.nop = $INTB(0) + $CHR(0) + $INTB(0) + $CHR(0) + $INTB(1) + $INTB(0)
$io.cmd.hdr = "Destination System Address" + "Destination queue ID"+"Source System Address" + " Source Queue ID" + "Function Code" + "Function Qualifier"
This string is a special string, in that since the function qualifier field is equal to zero, it informs the menu driver to do nothing, or "perform no operation". Notice that the first five fields contain exactly the same information as the $io.cmd.hdr string, so the following string definition would be true:
$io.cmd.nop=$io.cmd.hdr + $INTB(0)
The commands listed in I/O Buffer Qualifiers for Menu Commands Without Parameters do not use the variable data field of the I/O Communications Buffer. They are used to pass simple keyboard type commands to the menu driver via software, instead of actually waiting for keyboard input.
The most commonly used of the commands in I/O Buffer Qualifiers for Menu Commands Without Parameters is the ky.redraw command, which forces the current menu page to be redrawn. When a menu page is redrawn, all conditional sections are evaluated. Since "Conditional Sections" are only evaluated when the menu page is first drawn or each time the page is redrawn, sending a menu command that tells the menu driver to redraw the menu page is an efficient way to get all the conditional sections reevaluated at the customizer's discretion.
Each of the commands listed in I/O Buffer Qualifiers for Menu Commands Without Parameters will fill the "Function Qualifier" field in the buffer. For example, to send a redraw command back to the menu driver the following string would be defined in a spawn routine:
$cmd = $io.cmd.hdr + $INTB(ky.redraw)
The string variable $io.cmd.hdr in the above string definition contains all the necessary header data for the buffer up to the qualifier field. The qualifier data field is formatted as a 16 bit integer. Therefore, the $INTB( ) command is used to convert the 16 bit integer value into a 2 byte string containing the binary representation of the 16 bit integer.
Likewise, the V+ INTB( ) function can be used to extract the integer value from the string representation.
There are four buffer "qualifiers" that are used to perform more complex commands and require the use of the variable data section of the buffer. They are described in I/O Buffer Qualifiers for Menu Commands to Display Menu Pages and I/O Buffer Qualifiers for Menu Commands to Execute V+ Spawn Routines or a Sequence.
To make use of the these commands, the variable data section of the buffer must contain the data necessary to allow the menu driver to complete the requested command. The order of the data is critical for the success of the command. See Format of I/O Buffer Data Field for Page-Display Commands and Format of I/O Buffer Data Field for Spawn Commands.
For example, if you want to display a new menu page called USER from the menu file USERMENU.MNU, the following command string, returned from a spawn routine, will accomplish this task:
1 func = ky.menu 2 mode = 0 3 $page = "user" 4 $file = "usermenu.mnu" 5 type = 0 6 rec = 0 7 access.lvl = 3 8 norun = 0 9 CALL mu.set.goto(func, mode, $page, $file, type, rec, access.lvl, norun, $cmd)
The following is a line by line breakdown of the $CMD string:
Line 1 Requested command, ky.menu.
Line 4 ASCII text, menu file name.
Line 5 Primary database number.
Line 9 mu.set.goto (func, mode, $page, $file, type, rec, acc, norun, $cmd) builds the command header and returns it in $cmd. It takes care of adding required spaces and ensuring that the command header is in the proper format. The input items to mu.set.goto (func, mode, $page, $file, type, rec, acc, norun, $cmd) correspond to the command plus the first seven items in Format of I/O Buffer Data Field for Page-Display Commands.
There is a second program, mu.set.rtrv (type, rec, field, index, $cmd) that adds the command header items specified in the next four item in I/O Communications Buffers. For example, assume you have already built the first part of a command header using mu.set.goto (func, mode, $page, $file, type, rec, acc, norun, $cmd) and you want to retrieve information from field 4 of record 2 of the path database. The following code will complete the $cmd header (note that $cmd is both an input and output parameter):
CALL mu.set.rtrv(ph.db[TASK()], 2, 4, 0, $cmd)
The menu driver is configured to take care of the above commands when a new Menu Button is created. When you create a new menu button, fill in the menu file name and page in the Button Access section on the "Menu Button" data editing menu page, along with the primary database, user access level and sequence idle flag. Notice that these data values correspond to fields in the data section of the buffer defined above. The menu driver then takes care of assembling the data to display the menu page the user desires.
Using of the I/O Communications Buffer in AIM Customization
The following examples show how to make use of the I/O communications buffer for more effective AIM customization.
Example 1: Extracting Qualifier Data From The Buffer
This example shows how to determine the way a menu page was closed. Assume that the menu page named DATA in the menu file TEMP.MNU has three spawn routine buttons on it labeled DONE, YES, and NO. The spawn "Routine Name" data field on the button definition menu page contains the following for each button:
In the above example, using the V+ INTB( ) function with the appropriate OFFSET into the $cmd string (which is in the I/O Communications Buffer format), the ky.* variable that was encoded into this string by the menu driver is extracted and evaluated to determine which button was pressed by the operator. The offset io.qal is defined in Format of I/O Communications Buffer.
Example 2: Forcing a Menu Page Redraw from a Spawn Routine
This example will show how to force a menu page to be re-drawn at the end of a spawn routine. Remember, conditional sections get evaluated only when the menu page is drawn or re-drawn:
Example 3: Sending Error Information Back to The Menu Driver
This example shows how to send error information from a spawn routine back to the menu driver for display on the standard error menu page (the red/white menu page that has the error code and string on it).
The above call to db.search.str (db, field, index, $string, record, status) will search the name field in the current vision database for a record that has the name defined in the string $record.name. The output argument status will contain either a zero if successful, or a V+ error code that will indicate the failure of the search operation.
Notice that there are two $cmd string definitions in the above code. The second one will be encountered if all goes well with the processing of the spawn routine (i.e., no errors). This definition informs the menu driver to do nothing, or perform no operation. The first $cmd definition will only be executed in the event of an error. If the status output argument from db.search.str (db, field, index, $string, record, status) is less than zero, which indicates an error occurred, then execution jumps to label 100. If the error code is placed into the "Function Qualifier" field in the I/O Communications Buffer, the menu driver will automatically display the red/white error menu page with this code and its text displayed.