MPE/iX System Intrinsics

The MPE/iX system provides a set of subroutines, callable by your program, that help you interface with the file system to accomplish various tasks. These subroutines are an integral, or intrinsic, part of the operating system, and are therefore referred to as system intrinsics. Intrinsics exist which allow you to perform a variety of recurring tasks, ranging from manipulating individual file attributes to manipulating processes, if you have the needed capabilities.

Intrinsics are program segments, no different from the code you write yourself except that they are invisible to you. They are usually coded in Pascal/iX (system language for HP 3000 Series 900 computers), but are generally callable from any supported language.

This manual discusses the subset of system intrinsics that are most useful for dealing with communications between the system and an asynchronous device. It is intended to provide the reader with a high level of detail regarding the use of intrinsics for controlling such devices. A complete description of all the system intrinsics available to you can be found in the MPE/iX Intrinsics Reference Manual, along with details regarding their use.

With one exception, the intrinsics described in this manual can be used in both native mode and compatibility mode programs. The exception is the HPFOPEN intrinsic, which can be called from native mode programs only. (There are other MPE/iX intrinsics which can only be called from native mode programs, but HPFOPEN is the only one discussed in this manual.)

Intrinsics and Asynchronous Serial Communications

Certain system intrinsics are particularly useful to you for providing an interface between the ASC managers that handle serial device connections and the MPE/iX File System. These are primarily the intrinsics that provide simple mechanisms for accessing and altering files, handling I/O operations, and checking file status. The following list provides a summary of these intrinsics and their functions. For a more complete description of the syntax and use of these intrinsics see Chapter 8 “Intrinsics Reference” Additional information about the practical use of the intrinsics listed here can be found throughout this manual.

Summary of Intrinsics

INTRINSICS	PURPOSE
FCHECK	Requests details about file I/O errors.
FCLOSE	Closes a file.
FCONTROL	Performs a number of control operations on a file or device.
FDEVICECONTROL	Provides control operations to a printer, terminal, or spooled device.
FERRMSG	Obtains textual error message corresponding to an FCHECK error code.
FFILEINFO	Provides information about the characteristics of a file.
FGETINFO	Provides access and status information about a file.
FOPEN	Opens a file, defines its physical characteristics, and provides access to the file.
FREAD	Transfers a record of data from an input device to an array.
FSETMODE	Controls the output of linefeed.
FWRITE	Transfers a record of data to a file on any device.
HPFOPEN	Opens a file, defines its physical characteristics, and sets up access to the file. Provides access to mapped files.
IODONTWAIT	Initiates completion of a no-wait I/O request. Allows program processing to continue before an I/O operation completes.
IOWAIT	Initiates completion of a no-wait I/O request. Delays program processing until an I/O operation completes.
PRINT	Prints a character string on job/session list device.
PRINTFILEINFO	Prints a file information display on a job/session list device.
READ	Transfers a record of data from the file `$STDIN` into an array.
READX	Transfers a record of data from the file `$STDINX` into an array.
RESETCONTROL	Allows another subsystem break to occur.
XCONTRAP	Arms or disarms the user-written [CTRL]Y trap handling procedure.

You should note that the functions described here are specific to the way these intrinsics interact with and provide control for asynchronous communications ports. Many are useful for additional functions not described in this manual. See the MPE/iX Intrinsics Reference Manual for information about additional uses of these intrinsics.

Other Types of Intrinsics

The discussion in this manual pertains exclusively to system intrinsics. Certain application programs and system utilities also provide subroutines that are referred to as intrinsics. For example, VPLUS/3000 iX provides a set of intrinsics for handling page block mode programming. For a description of VPLUS/3000 iX intrinsics see the VPLUS Reference Manual. For descriptions of intrinsics provided by any other application or utility, see the documentation for that program.

Using Intrinsics in your Program

You can call any system intrinsic from any supported language, but the details of the calling procedure vary according to the language being used. In general, you should follow the steps as summarized:

Refer to the intrinsic description in Chapter 8 “Intrinsics Reference” to determine the parameter types and their positions in the parameter list.
Declare variables to be passed as parameters, using types appropriate to the language you are using to write your program.
Include the name of the intrinsic in a declaration statement, if appropriate for your programming language.
Issue the intrinsic call at the appropriate place in your program.

Depending on the intrinsic call, error checking is provided either through condition codes or through a special status parameter. Because the condition code or status return value can provide you with useful information about what happened during execution of an intrinsic, you should routinely check for error conditions at the completion of each intrinsic call.

Condition Codes

Most of the intrinsics discussed in this manual use condition codes for error checking. Condition codes are status flags stored in two bits of the status register. Their values and general meanings are shown in Table 2-1 “Condition Codes”. Because the condition code status flags are affected by almost every instruction, you should check condition codes immediately after execution of an intrinsic to make sure that the information being returned pertains to the intrinsic and not to some subsequent activity.

The method of accessing condition codes is language specific. Pascal/iX, for example, provides the function ccode, which returns the value 0, 1, or 2, depending on the current condition code stored in the status register. See the reference manual for the language you are using to determine how to access condition code information.

If the condition code indicates that an error condition occurred during execution of an intrinsic, you may want to obtain more specific information about what took place. You can do so by calling FCHECK to obtain details such as the error code associated with the problem that occurred, and FERRMSG to display the message associated with that error code. See the discussions of these intrinsics in the Intrinsics Reference section of this manual.

Table 2-1 Condition Codes

Condition Code	Value	General Meaning
CCE (=)	2	Condition Code Equal. This generally indicates that the request was granted.
CCG (>)	0	Condition Code Greater Than. A special condition occurred but may not have affected the execution of the request. (For example, the request was executed, but default values were assumed as intrinsic call parameters.)
CCL (<)	1	Condition Code Less Than. The request was not granted, but the error condition may be recoverable.

Status Parameter

While many intrinsics return an error parameter, only MPE/iX native mode intrinsics, such as the HPFOPEN intrinsic described in this manual, use the status parameter in place of condition codes as their error checking convention. The status parameter is a 32-bit signed integer which returns error information in one 16-bit field and subsystem information in its other 16-bit field.

The information returned by the status parameter is more explicit than that available through condition codes. The intrinsics that use the status parameter do not return meaningful condition code values.

The status parameter is optional, but it is strongly advised that you use this feature whenever it is provided. If an error or warning condition is encountered during execution of a native mode intrinsic and you did not specify the status parameter, the intrinsic causes the calling process to abort.

See the discussion of HPFOPEN in this manual, as well as the MPE/iX Intrinsics Reference Manual for more information on using the status parameter.

Abort Errors

The errors that return condition code or status information to your program are generally recoverable and do not cause your program to abort. Another type of error occurs if a calling program attempts to pass illegal parameters to an intrinsic or does not have the capabilities needed to execute an intrinsic. Such an error is called an abort error and results in termination of the process.

Optional Capabilities

A number of system intrinsics can be used in a program only if you have optional capabilities assigned to you. Optional capabilities are assigned when your account is created, but can be altered by the System Manager or Account Manager through use of appropriate MPE/iX commands. See the MPE/iX Commands Reference Manual for more information on how to alter the capabilities assigned to an account, group or user.

If your program calls intrinsics which require optional capabilities you must prepare the program with these capabilities specified. Such a program can be run by users without the specific capabilities as long as it resides in a group with the proper capabilities assigned.

None of the intrinsics discussed in this manual require optional capabilities; however, if you intend to use NOWAIT I/O, you must have specified the NOWAIT option in the FOPEN or HPFOPEN call used to open the file. Specification of NOWAIT I/O requires that you have Privileged Mode (PM) capability. Once NOWAIT I/O has been specified you can control completion operations for I/O requests by calling the IOWAIT or IODONTWAIT intrinsics, as described in Chapter 8 “Intrinsics Reference”




	CAUTION: The normal checks and limitations that apply to users with standard (default) capabilities are bypassed in Privileged Mode. It is possible for a Privileged Mode program to destroy file integrity, including the MPE/iX operating system software itself. Hewlett-Packard will, upon request, investigate and attempt to resolve problems resulting from the use of Privileged Mode code. This service, which is not provided under the standard Service Contract, is available on a time and materials billing basis. Hewlett-Packard will not support, correct, or attend to any modification of the MPE/iX operating system software.

Obtaining Information Using Intrinsics

Some intrinsics return information to the calling process, either as a value returned in one of the positional parameters, or through the special device used to designate functional return information.

Status Information

A number of intrinsics include output parameters in their parameter lists and can therefore be used to determine information about current device settings or devicefile specifications. The values returned in this way are a report of current status, rather than a result of intrinsic activity.

FGETINFO is an example of such an intrinsic. FGETINFO is called with the file number of the file about which you are requesting information specified in its first positional parameter. (The file number is obtained through an FOPEN or HPFOPEN call initiated by the calling process.) Access and status information about the file is returned in the other FGETINFO positional parameters. Information that can be obtained through a call to FGETINFO includes which file characteristics are in effect, the logical size of records in the file, the configured device type, and more. See Chapter 8 “Intrinsics Reference” for a complete list of the information that can be obtained through a call to FGETINFO.

Some intrinsics contain a mixture of input and output parameters in their parameter lists. For example, some intrinsics return a file system error number in one of the parameters if an error message occurs during processing.

A special case exists for the FCONTROL intrinsic. FCONTROL provides a variety of control functions for files or devices, based on the value of a control code specified by the second parameter in its parameter list. The value of the second parameter determines the content of the third parameter, and whether it is used for input, for output, or both. In some cases the third parameter is used to set a value, while in other cases it returns a current status. In a few cases this parameter passes a new value and returns the previous value to the program in the same call. FCONTROL functions are discussed throughout this manual.

Functional Returns

Some intrinsics return a value to the calling program through a functional return. Functional return values result from or are altered by the intrinsics of which they are a part. In examples and calling syntax depicted in this manual, they are shown in assignment statements, with the symbol := used as the operator to designate that the functional return parameter is assigned the value of the result of the intrinsic call. The functional return parameter is shown on the left of the operator, with the call to the intrinsic on the right, as in the following example:

lgth:=FREAD(filenum,buffer,length);

Keep in mind that while functional returns are always demonstrated in assignment statements in this manual they need not be used exclusively in this way. They can also be used in output statements, as one of the parameters in a parameter list, and in conditional statements.

Unlike the values returned in positional parameters, which are a report of current status, functional return values are the result of the activity of the intrinsic. The FREAD intrinsic reports back the length of the message read. Likewise, the FOPEN (and HPFOPEN) intrinsic reports back a file number, which can then be used by other intrinsics called by the same program.

The intrinsics discussed in this manual which yield functional return values are FOPEN, FREAD, IOWAIT, IODONTWAIT, READ and READX. See Chapter 8 “Intrinsics Reference” for their usage and syntax descriptions.