HP 900 3000 computer system Reference manual

900 Series HP 3000 Computer Systems
MPE/iX Intrinsics Reference Manual
ABCDE
HP Part No. 32650-90028
Printed in U.S.A.
1995
Sixth Edition Update
E0195
The information contained in this document is subject to change
without notice.
Hewlett-Packard makes no warranty of any kind with regard to this
material, including, but not limited to, the implied warranties of
merchantability or tness for a particular purpose. Hewlett-Packard
shall not be liable for errors contained herein or for direct, indirect,
special, incidental or consequential damages in connection with the
furnishing or use of this material.
Hewlett-Packard assumes no responsibility for the use or reliability of
its software on equipment that is not furnished by Hewlett-Packard.
This document contains proprietary information which is protected
by copyright. All rights are reserved. Reproduction, adaptation, or
translation without prior written permission is prohibited, except as
allowed under the copyright laws.
Copyright c 1995 by Hewlett-Packard Company
Use, duplication, or disclosure by the U.S. Government is subject
to restrictions as set forth in subparagraph (c) (1) (ii) of the
Rights in Technical Data and Computer Software clause at DFARS
252.227-7013. Rights for non-DoD U.S. Government Departments and
agencies are as set forth in FAR 52.227-19 (c) (1,2).
Hewlett-Packard Company
3000 Hanover Street
Palo Alto, CA 94304 U.S.A.
Restricted Rights Legend
Printing History
The following table lists the printings of this document, together with the respective release
dates for each edition. The software version indicates the version of the software product
at the time this document was issued. Many product releases do not require changes to the
document. Therefore, do not expect a one-to-one correspondence between product releases
and document editions.
Edition
Date
Software Version
First Edition
First Edition Update 1
First Edition Update 2
Second Edition
Third Edition
Fourth Edition
Fifth Edition
Sixth Edition
Sixth Edition Update
November 1987
July 1988
December 1988
October 1989
April 1990
December 1990
June 1992
April 1994
January 1995
A.01.00
A.10.00
A.20.00
A.20.00
A.40.00
B.30.00
B.40.00
C.50.00
C.50.00
iii
iv
Preface
MPE/iX, Multiprogramming Executive with Integrated POSIX, is the latest in a series of
forward-compatible operating systems for the HP 3000 line of computers.
In HP documentation and in talking with HP 3000 users, you will encounter references to
MPE XL, the direct predecessor of MPE/iX. MPE/iX is a superset of MPE XL. All programs
written for MPE XL will run without change under MPE/iX You can continue to use MPE
XL system documentation, although it may not refer to features added to the operating
system to support POSIX (for example, hierarchical directories).
Finally, you may encounter references to MPE V, which is the operating system for HP 3000s,
not based on PA-RISC architecture. MPE V software can be run on the PA-RISC (Series 900)
HP 3000s in what is known as compatibility mode .
v
vi
Conventions
UPPERCASE
In a syntax statement, commands and keywords are shown in
uppercase characters. The characters must be entered in the order
shown; however, you can enter the characters in either uppercase or
lowercase. For example:
COMMAND
can be entered as any of the following:
command
Command
COMMAND
It cannot, however, be entered as:
comm
italics
bold italics
com_mand
comamnd
In a syntax statement or an example, a word in italics represents a
parameter or argument that you must replace with the actual value.
In the following example, you must replace lename with the name
of the le:
COMMAND lename
In a syntax statement, a word in bold italics represents a parameter
that you must replace with the actual value. In the following
example, you must replace lename with the name of the le:
COMMAND(lename)
punctuation
In a syntax statement, punctuation characters (other than brackets,
braces, vertical bars, and ellipses) must be entered exactly as shown.
In the following example, the parentheses and colon must be entered:
(lename):(lename)
underlining
Within an example that contains interactive dialog, user input and
user responses to prompts are indicated by underlining. In the
following example, yes is the user's response to the prompt:
Do you want to continue? >> yes
{
}
In a syntax statement, braces enclose required elements. When
several elements are stacked within braces, you must select one. In
the following example, you must select either ON or OFF:
COMMAND
[
]
ON
OFF
In a syntax statement, brackets enclose optional elements. In the
following example, OPTION can be omitted:
COMMAND lename [OPTION]
When several elements are stacked within brackets, you can select
one or none of the elements. In the following example, you can select
OPTION or parameter or neither. The elements cannot be repeated.
COMMAND lename
OPTION
parameter
vii
Conventions (continued)
[ ... ]
In a syntax statement, horizontal ellipses enclosed in brackets
indicate that you can repeatedly select the element(s) that appear
within the immediately preceding pair of brackets or braces. In the
example below, you can select parameter zero or more times. Each
instance of parameter must be preceded by a comma:
[,parameter][...]
In the example below, you only use the comma as a delimiter if
parameter is repeated; no comma is used before the rst occurrence
of parameter :
[parameter][,...]
| ... |
In a syntax statement, horizontal ellipses enclosed in vertical bars
indicate that you can select more than one element within the
immediately preceding pair of brackets or braces. However, each
particular element can only be selected once. In the following
example, you must select A, AB, BA, or B. The elements cannot be
repeated.
A
| ... |
B
...
In an example, horizontal or vertical ellipses indicate where portions
of an example have been omitted.
In a syntax statement, the space symbol 1 shows a required blank.
In the following example, parameter and parameter must be
separated with a blank:
1
(parameter)1(parameter)
The symbol 4 5 indicates a key on the keyboard. For example,
4RETURN5 represents the carriage return key or 4Shift5 represents the
shift key.
4CTRL5character 4CTRL5character indicates a control character. For example, 4CTRL5Y
means that you press the control key and the Y key simultaneously.
4
viii
5
Contents
1. Introduction
What Is an Intrinsic? . . . . . . . . . . . . . . . . . . . . . . . . .
What Is an Intrinsic Mechanism? . . . . . . . . . . . . . . . . . . . .
2. Intrinsic Use
Parameters . . . . . . . . . . .
Parameter Declarations . . . .
Parameter Alignment . . . . .
Parameter Bit Settings . . . .
Syntax Statement Mnemonics .
Itemnum and Item Pair Options
Data Type Mappings . . . . .
Functional Returns . . . . . . .
Error Handling . . . . . . . . .
Condition Code Errors . . . . .
Status Parameter Errors . . . .
Abort Errors . . . . . . . . .
Additional Capabilities Required .
DS Capability . . . . . . . .
LG Capability . . . . . . . .
MR Capability . . . . . . . .
ND Capability . . . . . . . .
OP Capability . . . . . . . .
PH Capability . . . . . . . .
PM Capability . . . . . . . .
PS Capability . . . . . . . .
1-2
1-3
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-1
2-1
2-2
2-2
2-3
2-4
2-5
2-7
2-8
2-8
2-9
2-12
2-13
2-14
2-14
2-14
2-14
2-14
2-15
2-15
2-15
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-2
4-4
4-6
4-8
4-10
4-12
4-15
4-17
4-19
4-21
4-22
4-23
3. Intrinsic Tasks
4. Command Denitions
ABORTSESS . . . .
ACTIVATE . . . .
ADJUSTUSLF . . .
ALMANAC . . . .
ALTDSEG . . . . .
ARITRAP . . . . .
ASCII . . . . . . .
BEGINLOG . . . .
BINARY . . . . . .
CALENDAR . . . .
CATCLOSE . . . .
CATOPEN . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents-1
CATREAD . . . .
CAUSEBREAK . .
CLEANUSL . . . .
CLOCK . . . . . .
CLOSELOG . . . .
COMMAND . . . .
CREATE . . . . .
CREATEPROCESS .
CTRANSLATE . . .
DASCII . . . . . .
DATELINE . . . .
DBINARY . . . . .
DEBUG . . . . . .
DLSIZE . . . . . .
DMOVIN . . . . .
DMOVOUT . . . .
ENDLOG . . . . .
EXPANDUSLF . . .
FATHER . . . . .
FCHECK . . . . .
FCLOSE . . . . . .
FCONTROL . . . .
FDELETE . . . . .
FDEVICECONTROL
FERRMSG . . . .
FFILEINFO . . . .
FFINDBYKEY . . .
FFINDN . . . . . .
FGETINFO . . . .
FGETKEYINFO . .
FINDJCW . . . . .
FINTEXIT . . . . .
FINTSTATE . . . .
FLABELINFO . . .
FLOCK . . . . . .
FLUSHLOG . . . .
FMTCALENDAR .
FMTCLOCK . . . .
FMTDATE . . . .
FOPEN . . . . . .
FPARSE . . . . . .
FPOINT . . . . . .
FREAD . . . . . .
FREADBACKWARD
FREADBYKEY . .
FREADC . . . . .
FREADDIR . . . .
FREADLABEL . . .
FREADSEEK . . .
FREEDSEG . . . .
FREELOCRIN . . .
Contents-2
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-25
4-28
4-29
4-31
4-32
4-34
4-36
4-43
4-48
4-50
4-52
4-53
4-55
4-56
4-58
4-61
4-64
4-66
4-68
4-69
4-79
4-84
4-107
4-108
4-130
4-131
4-151
4-153
4-155
4-164
4-166
4-168
4-169
4-171
4-182
4-184
4-185
4-186
4-187
4-189
4-218
4-221
4-223
4-226
4-228
4-230
4-232
4-234
4-236
4-238
4-240
FRELATE . . . . . . . .
FREMOVE . . . . . . .
FRENAME . . . . . . .
FSETMODE . . . . . . .
FSPACE . . . . . . . . .
FUNLOCK . . . . . . .
FUPDATE . . . . . . . .
FWRITE . . . . . . . .
FWRITEDIR . . . . . .
FWRITELABEL . . . . .
GENMESSAGE . . . . .
GETDSEG . . . . . . . .
GETINFO . . . . . . . .
GETJCW . . . . . . . .
GETLOCRIN . . . . . .
GETORIGIN . . . . . . .
GETPRIORITY . . . . .
GETPRIVMODE . . . . .
GETPROCID . . . . . .
GETPROCINFO . . . . .
GETUSERMODE . . . .
HP32208 . . . . . . . . .
HPACDINFO . . . . . .
HPACDPUT . . . . . . .
HPCICOMMAND . . . .
HPCIDELETEVAR . . . .
HPCIGETVAR . . . . . .
HPCIPUTVAR . . . . . .
HPDEBUG . . . . . . .
HPDEVCONTROL . . . .
HPDEVCREATE . . . . .
HPENBLTRAP . . . . . .
HPERRDEPTH . . . . .
HPERRMSG . . . . . . .
HPERRREAD . . . . . .
HPFDUPLICATE . . . .
HPFIRSTLIBRARY . . .
HPFOPEN . . . . . . . .
HPFPCONVERT . . . . .
HPGETPROCPLABEL . .
HPLOADCMPROCEDURE
HPLOADNMPROC . . . .
HPMERGEEND . . . . .
HPMERGEERRORMESS .
HPMERGEINIT . . . . .
HPMERGEOUTPUT . . .
HPMERGESTAT . . . . .
HPMERGETITLE . . . .
HPMYFILE . . . . . . .
HPMYPROGRAM . . . .
HPPIPE . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-241
4-243
4-244
4-247
4-250
4-252
4-253
4-255
4-263
4-265
4-267
4-272
4-275
4-277
4-278
4-279
4-280
4-282
4-283
4-284
4-286
4-287
4-288
4-294
4-298
4-300
4-301
4-305
4-308
4-310
4-312
4-316
4-319
4-321
4-325
4-327
4-329
4-331
4-364
4-368
4-371
4-373
4-375
4-376
4-378
4-383
4-384
4-386
4-387
4-389
4-392
Contents-3
HPRESETDUMP . . . . . .
HPSELECT . . . . . . . .
HPSETCCODE . . . . . .
HPSETDUMP . . . . . . .
HPSORTEND . . . . . . .
HPSORTERRORMESS . . .
HPSORTINIT . . . . . . .
HPSORTINPUT . . . . . .
HPSORTOUTPUT . . . . .
HPSORTSTAT . . . . . . .
HPSORTTITLE . . . . . .
HPSWITCHTOCM . . . . .
HPSWTONMNAME . . . .
HPSWTONMPLABEL . . .
HPUNLOADCMPROCEDURE
HPVOLINFO . . . . . . .
INITUSLF . . . . . . . . .
IODONTWAIT . . . . . . .
IOWAIT . . . . . . . . . .
JOBINFO . . . . . . . . .
KILL . . . . . . . . . . .
LOADPROC . . . . . . . .
LOCKGLORIN . . . . . . .
LOCKLOCRIN . . . . . . .
LOCRINOWNER . . . . . .
LOGINFO . . . . . . . . .
LOGSTATUS . . . . . . .
MAIL . . . . . . . . . . .
MERGEEND . . . . . . . .
MERGEERRORMESS . . .
MERGEINIT . . . . . . . .
MERGEOUTPUT . . . . .
MERGESTAT . . . . . . .
MERGETITLE . . . . . . .
MYCOMMAND . . . . . .
NLAPPEND . . . . . . . .
NLCOLLATE . . . . . . .
NLCOLLATE2 . . . . . . .
NLCONVCLOCK . . . . . .
NLCONVCUSTDATE . . . .
NLCONVNUM . . . . . . .
NLFINDSTR . . . . . . . .
NLFMTCALENDAR . . . .
NLFMTCLOCK . . . . . .
NLFMTCUSTDATE . . . .
NLFMTDATE . . . . . . .
NLFMTLONGCAL . . . . .
NLFMTNUM . . . . . . .
NLGETLANG . . . . . . .
NLINFO . . . . . . . . . .
NLJUDGE . . . . . . . . .
Contents-4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-394
4-395
4-399
4-401
4-403
4-405
4-406
4-411
4-412
4-414
4-416
4-417
4-419
4-421
4-423
4-425
4-446
4-448
4-450
4-452
4-459
4-460
4-462
4-464
4-466
4-468
4-470
4-472
4-474
4-475
4-476
4-481
4-482
4-483
4-484
4-488
4-489
4-491
4-493
4-495
4-497
4-500
4-502
4-504
4-506
4-508
4-510
4-512
4-516
4-518
4-526
NLKEYCOMPARE .
NLMATCH . . . .
NLMATCHINIT . .
NLNUMSPEC . . .
NLREPCHAR . . .
NLSCANMOVE . .
NLSUBSTR . . . .
NLSWITCHBUF . .
NLTRANSLATE . .
OPENLOG . . . .
PAUSE . . . . . .
PRINT . . . . . .
PRINTFILEINFO .
PRINTOP . . . . .
PRINTOPREPLY .
PROCINFO . . . .
PROCTIME . . . .
PUTJCW . . . . .
QUIT . . . . . . .
QUITPROG . . . .
READ . . . . . . .
READX . . . . . .
RECEIVEMAIL . .
RESETCONTROL .
RESETDUMP . . .
SEARCH . . . . .
SENDMAIL . . . .
SETDUMP . . . .
SETJCW . . . . .
SORTEND . . . . .
SORTERRORMESS
SORTINIT . . . . .
SORTINPUT . . . .
SORTOUTPUT . .
SORTSTAT . . . .
SORTTITLE . . . .
STACKDUMP . . .
STARTSESS . . . .
SUSPEND . . . . .
SWITCHDB . . . .
TERMINATE . . .
TIMER . . . . . .
UNLOADPROC . .
UNLOCKGLORIN .
UNLOCKLOCRIN .
WHO . . . . . . .
WRITELOG . . . .
XARITRAP . . . .
XCONTRAP . . . .
XLIBTRAP . . . .
XSYSTRAP . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-528
4-531
4-532
4-535
4-537
4-539
4-542
4-545
4-548
4-550
4-552
4-553
4-554
4-555
4-557
4-559
4-565
4-566
4-568
4-569
4-570
4-572
4-574
4-576
4-577
4-578
4-580
4-582
4-584
4-585
4-586
4-587
4-592
4-593
4-595
4-596
4-597
4-599
4-604
4-606
4-607
4-608
4-609
4-610
4-611
4-612
4-615
4-617
4-622
4-624
4-626
Contents-5
ZSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index
Contents-6
4-628
Figures
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
DMOVIN Data Movement. . .
DMOVOUT Data Movement.
Foption Bit Summary . . . .
Aoption Bit Summary . . . .
Foption Bit Summary . . . .
Aoption Bit Summary . . . .
Foption Bit Summary . . . .
Carriage Control Byte . . . .
Carriage-Control Data . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-59
4-62
4-149
4-150
4-162
4-163
4-181
4-225
4-260
Contents-7
Tables
2-1.
2-2.
2-3.
2-4.
2-5.
2-6.
3-1.
3-2.
3-3.
3-4.
3-5.
3-6.
3-7.
3-8.
3-9.
3-10.
3-11.
3-12.
3-13.
3-14.
3-15.
3-16.
3-17.
3-18.
3-19.
3-20.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
4-10.
4-11.
4-12.
4-13.
4-14.
4-15.
4-16.
4-17.
Mnemonic Descriptions . . . . . . . . . . . . . .
Data Type Mappings . . . . . . . . . . . . . . .
Condition Code Descriptions . . . . . . . . . . . .
Status.subsys Parameter Identiers . . . . . . . . .
Status.info Parameter Identiers . . . . . . . . . .
Additional Capabilities Required . . . . . . . . . .
Accessing Files . . . . . . . . . . . . . . . . . .
Accessing Command Interpreter Features . . . . . .
Getting System Information . . . . . . . . . . . .
Managing Processes . . . . . . . . . . . . . . . .
Managing Resources . . . . . . . . . . . . . . . .
Programming for Localization . . . . . . . . . . .
Managing Message Catalogs . . . . . . . . . . . .
Converting Data Types . . . . . . . . . . . . . .
Sorting and Merging Data . . . . . . . . . . . . .
Handling Traps . . . . . . . . . . . . . . . . . .
Managing Logging Facilities . . . . . . . . . . . .
Debugging Applications . . . . . . . . . . . . . .
Obtaining Device Information . . . . . . . . . . .
Programming in Privileged mode . . . . . . . . . .
Managing USL Files . . . . . . . . . . . . . . . .
Managing Data Segments . . . . . . . . . . . . .
Changing Stack Size . . . . . . . . . . . . . . . .
Using the Compiler Library . . . . . . . . . . . .
Programming Switch . . . . . . . . . . . . . . .
Controlling Asynchronous Devices . . . . . . . . . .
CREATEPROCESS Itemnum/Item Values . . . . . .
File System Error Codes . . . . . . . . . . . . . .
FCONTROL Itemnum/Item Values . . . . . . . . .
FDEVICECONTROL Controlcode/Parm1,Parm2 Values
FDEVICECONTROL Controlcode 192 Values . . . .
FFILEINFO Itemnum/Item Values . . . . . . . . .
FFILEINFO File Codes . . . . . . . . . . . . . .
FLABELINFO Itemnum/Item Values . . . . . . . .
FOPEN/HPFOPEN Parameter Equivalents . . . . .
Carriage-Control Directives . . . . . . . . . . . .
HPACDINFO Itemnum1/Item1 Values . . . . . . .
HPACDINFO Itemnum2/Item2 Values . . . . . . .
HPACDPUT Itemnum1/Item1 Values . . . . . . . .
HPACDPUT Itemnum2/Item2 Values . . . . . . . .
HPCIGETVAR Itemnum/Item Values . . . . . . . .
HPCIPUTVAR Itemnum/Item Values . . . . . . . .
HPDEBUG Itemnum/Item Values . . . . . . . . .
Contents-8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-4
2-6
2-8
2-10
2-11
2-13
3-2
3-3
3-4
3-5
3-5
3-6
3-6
3-7
3-7
3-8
3-8
3-8
3-9
3-9
3-9
3-9
3-9
3-10
3-10
3-11
4-45
4-70
4-85
4-110
4-128
4-132
4-146
4-174
4-216
4-258
4-290
4-291
4-295
4-296
4-303
4-306
4-309
4-18.
4-19.
4-20.
4-21.
4-22.
4-23.
4-24.
4-25.
4-26.
4-27.
HPDEVCONTROL Itemnum/Item Values
HPDEVCREATE Keywords/Keyvalues .
HPFOPEN Itemnum/Item Values . . . .
. . . . . . . . . . . . . . . . . . .
JOBINFO Itemnum/Item Values . . . .
LOGINFO Itemnum/Item Values . . . .
NLINFO Itemnum/Item Values . . . . .
PROCINFO Error1,Error2 Values . . . .
PROCINFO Itemnum/Item Values . . .
STARTSESS Status Returns . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-311
4-314
4-333
4-393
4-454
4-469
4-520
4-560
4-561
4-600
Contents-9
1
Introduction
Many programs use procedures or subroutines to handle recurring tasks. In the MPE/iX
operating system many of these tasks are performed by a set of system procedures called
intrinsics. Intrinsics are available to any process which has the capabilities required to call the
intrinsic.
The tasks that intrinsics handle include:
Accessing and altering les
Requesting various utility functions
Accessing system resources
Manipulating and managing processes and system resources
Returning values to a caller through the use of parameters or functional returns
Intrinsics are no dierent from procedures that you would write for yourself, except that the
details of performing a task are invisible.
Introduction
1-1
What Is an Intrinsic?
The term intrinsic refers to any external system or subsystem. However, under MPE/iX this
term has a more specic meaning. To qualify as a true Hewlett-Packard documented and
user-callable intrinsic, it must meet the following criteria:
An intrinsic is a Hewlett-Packard supported external interface to an operating system or
subsystem service.
An intrinsic performs type and bounds checks on parameter values before it uses them, thus
protecting the operating system and the user from one another.
An intrinsic is documented in a Hewlett-Packard manual.
If an intrinsic is enhanced, its interface, capabilities, and feature set remain backward
compatible.
A process may call an intrinsic from any Hewlett-Packard supported programming language.
An intrinsic diers from other system library procedures
Hewlett-Packard subsystems and applications can also provide interfaces that meet the
denition of an intrinsic. Refer to the
MPE/iX Documentation Guide (32650-90144) for further information.
Note
1-2
You can dene routines for access as if they were intrinsics and place them in
new or existing intrinsic les and libraries.
Introduction
What Is an Intrinsic Mechanism?
The MPE/iX intrinsics mechanism provides exible and convenient access to intrinsic routines
from various languages. When an external routine is designated as an intrinsic, the compiler
uses the intrinsics mechanism to determine how to invoke the routine correctly. For example,
a compiler receives information about the number of parameters, the type of each parameter,
and the functional return type (if applicable) and does the following:
Provides a consistent intrinsic interface
Reduces the burden and error potential of coding multiple external procedure declarations
with all the parameters and type declarations required in some languages
Ensures proper data type conversion
Veries proper data alignment
Provides proper indirect address references to data
Generates proper reference parameter addresses
Assigns values to default parameters and correctly resolves optional parameters omitted at
the end of an intrinsic call
Provides parameter checking for languages that have no mechanism for detailed external
declarations
Permits inter-language calls that may not be possible within a particular programming
language
Provides name translation for case-insensitive languages
Allows future extension without requiring source code changes
For example, Pascal/XL requires a detailed routine header for all external routines, and all
calls to a routine must adhere to strict typing constraints. However, by designating a routine
as an intrinsic, the compiler uses the intrinsics mechanism to determine how to call the
routine which permits removal of the detailed routine header and relaxes the strict typing
constraints.
Since the type information, stored in the intrinsic mechanism, is in language-independent
form, you can pass parameters of any type that conform functionally to the types expected
by the intrinsic. This allows convenient and exible access to system intrinsics through the
intrinsics mechanism.
Note
You can dene routines for access as if they were intrinsics and place them in
new or existing intrinsic les and libraries.
Introduction
1-3
2
Intrinsic Use
You invoke an intrinsic by calling it explicitly from within a program, subprogram, or
procedure. All system intrinsics are treated as external procedures by user programs and the
intrinsics mechanism facilitates the declaration.
To call an intrinsic, you must know the following information:
The number of parameters and whether any are optional
The data type of each parameter and whether parameters are passed by value or reference
The calling sequence or order of the parameters
The functional return value, if applicable
Parameters
Intrinsic parameters can be input, output, or input/output (I/O) parameters:
Input parameters pass values into the intrinsic routine.
Output parameters return values from the intrinsic routine to the calling routine.
I/O parameters pass values into and return values from the intrinsic routine.
Parameter Declarations
Parameters are passed to an intrinsic either by value or by reference, depending on how the
parameter is declared. When a parameter is passed by reference, its address in the caller's
data area is made available to the called procedure. When a parameter is passed by value,
the called procedure receives a private copy of the actual data value. If the called procedure
changes the private copy, the corresponding value in the calling routine remains unchanged.
Parameters can be either a literal value or a variable; however, only variables can be passed to
reference parameters.
Intrinsic Use
2-1
A process must call intrinsic parameters in the exact calling sequence (order) specied in
the syntax statement and must separate them by commas. For example, write a call to the
CLOSELOG intrinsic as follows:
CLOSELOG(ACCESS,0,0);
You must represent optional intrinsic parameters if they are missing. To indicate a missing
parameter within the parameter list, omit the parameter, but retain the preceding commas.
For example, write a call to the FOPEN intrinsic and omit the second (optional) parameter as
follows:
FILENUM:=FOPEN(MYFILE,,3);
If you omit the rst parameter from a list, indicate this by following the left parenthesis with
a comma ((,). If you omit one or more parameters from the end of a list, indicate this by
following the last parameter with the right parenthesis; no commas are required.
Note
When a process calls an intrinsic with no parameters from C/XL, follow the
intrinsic name with an empty pair of parentheses (()).
Parameter Alignment
For programs running under MPE V and in compatability mode (CM), parameters are passed
by word address, which automatically enforces parameter alignment.
For programs running in native mode (NM), byte addressing is used for all parameters. As a
result, it is possible to pass a 16-bit or 32-bit parameter that is not 16-bit or 32-bit aligned.
Unless explicitly stated in the parameter description, native mode programs do not impose
alignment requirements.
Parameter Bit Settings
In some intrinsic calls, a process passes input parameters to the intrinsic as words whose
individual bits or elds of bits signify functions or options. In cases where bits within a word
are described as reserved for the operating system, set those bits to zero. This ensures the
compatibility of your current program with future releases of the operating system.
In some intrinsic calls, an intrinsic passes output parameters to words referenced by a calling
program. In cases where bits within a word are described as reserved for the operating
system, the system sets them to zero unless otherwise noted.
2-2
Intrinsic Use
Syntax Statement Mnemonics
An intrinsic's syntax statement contains the calling sequence, or order, of the parameters,
indicates whether a parameter is required or optional, and species the parameter type.
Syntax statements have the following format:
I16V U16V
ACTIVATE(pin,allow);
Required parameters, such as pin in the example above, appear in boldface italics. Optional
parameters, such as allow , are shown in italics . The mnemonics that appear over the
parameters indicate their type and whether they are passed by reference, which is the default,
and is not marked, or by value. (In the example, the mnemonics for both parameters have a
V, which indicates that they are passed by value.)
Table 2-1 lists the mnemonics used in intrinsic syntax statements and their meanings.
Intrinsic Use
2-3
Table 2-1. Mnemonic Descriptions
Mnemonic
Meaning
A
Array
B
Boolean
C
Character
CA
Character Array
I16
16-bit signed integer
I32
32-bit signed integer
I64
64-bit signed integer
I*
32-bit signed integer (NM) or 16-bit signed integer (CM)
LA
Logical array
O-P
Option privileged (privileged mode (PM) capability)
REC
Record
R32
32-bit real number
R64
64-bit real number
UDS
User-dened structure
U16
16-bit unsigned integer
U32
32-bit unsigned integer
U64
64-bit unsigned integer
V
Passed by value
@32
32-bit address
@64
64-bit address
@*
32-bit address (NM) or 16-bit address (CM)
*
Type varies
Itemnum and Item
Pair Options
Some intrinsics allow multiple itemnum,item pairs to be passed to dene one or more options.
The itemnum parameter is usually an integer value that the intrinsic uses to dene the
meaning and the expected data type of the value passed or returned in the corresponding item
parameter.
An itemnum cannot be passed without its corresponding item value. The only exception is
when a special value is passed in the last itemnum to indicate the end of the itemnum,item
list; in this case, an accompanying item is not required.
2-4
Intrinsic Use
Data Type Mappings
Table 2-2 maps generic data types to possible implementations in programming languages
supported by the operating system. The mnemonics associated with the generic types appear
in parentheses. For more information on calling intrinsics from these languages, refer to the
appropriate language reference manual.
Note
The IEEE oating-point standard is the default real format for the 900 Series
Hewlett-Packard 3000 computers.
Intrinsic Use
2-5
Table 2-2. Data Type Mappings
Generic Type
COBOL II/XL
FORTRAN 77/XL
Pascal/XL
C & C/XL
16-bit signed
integer (I16)
PIC S9(1) - S9(4)
BINARY SYNC
Integer*2
SHORTINT or any SHORTINT
16-bit subrange
32-bit signed
integer (I32)
PIC S9(5) - S9(9)
BINARY SYNC
Integer or
integer*4
Integer or any
32-bit subrange
32-bit
64-bit signed
integer (I64)
PIC S9(10) S9(18) BINARY
SYNC
N/A
N/A
N/A
16-bit unsigned
integer (U16)
PIC S9(1) - S9(4)
BINARY SYNC
Integer*2
0..65535 or any
16-bit subrange
Unsigned short
32-bit unsigned
integer (U32)
PIC S9(5) - S9(9)
BINARY SYNC
Integer or
integer*4
Any 32-bit
subrange
Unsigned integer
64-bit unsigned
integer (U64)
PIC S9(10) S9(18) BINARY
SYNC
N/A
N/A
N/A
32-bit real (R32)
N/A
Real or real*4
Real
Float
64-bit real (R64)
N/A
Double precision
or real*8
Long real
Double
Boolean (B)
Group item
Logical*2
Boolean
SHORTINT
Character (C)
USAGE DISPLAY Character
or group item
Char
Unsigned character
or character
32-bit address
(@32)
PIC S9(5) - S9(9)
BINARY SYNC
Integer or
integer*4
LOCALANYPTR or
Pointer
64-bit address
(@64)
PIC S9(10) S9(18) BINARY
SYNC
N/A
GLOBALANYPTR or
Long pointer
any normal pointer
type
any pointer type
declared with the
$EXTNADDR
compiler directive
Array (A)
USAGE DISPLAY Equivalent array
type
or group item
Array (any type)
Record (REC)
USAGE DISPLAY Array type
or group item
Record (any type) Struct (any type)
User-dened
structure (UDS)
2-6
Intrinsic Use
Array (any type)
Functional Returns
Certain intrinsics return a value to the calling program in functional returns. These routines
return a specied value type (for example, 16-bit signed integer, character, or 64-bit real) in
its name.
Functional returns are declared in an assignment statement, where the value returned is
assigned to some variable of the same type as the functional return. The symbol := is the
assignment operator that is \assigned the value of" or \receives the value of". The variable
receiving the functional return appears on the left-hand side of the assignment operator, while
the call to the intrinsic with a functional return appears on the right-hand side.
For example, an intrinsic call description format for functional returns appears below with the
READ intrinsic, which returns to a 16-bit signed integer indicating the length of the input read.
The data type of each variable is signied by a mnemonic above the variable name:
I16
U16A
I16V
length:=READ(message,expected);
The READ intrinsic is read as a 16-bit signed integer procedure, where message is a required
16-bit unsigned integer array passed by reference and expected is a required 16-bit integer
passed by value.
Other expressions that can contain calls to an intrinsic with a functional return can appear in
an output statement, the parameter list of a procedure, or a conditional statement. Refer to
the individual programmer's language and reference manuals for details on functional returns.
Intrinsic Use
2-7
Error Handling
Three types of errors can occur when an intrinsic is executed:
Condition code errors. Such errors are generally recoverable since control returns to the
calling program. The operating system maintains condition codes to provide backward
compatibility with previous (MPE V/E-based) operating systems.
Status parameter errors. When you include the status parameter in the intrinsic call, it
returns status information to the calling routine. For some intrinsics, both the condition
code and the special status parameter can return information; other intrinsics use only one
of these to return information.
Abort errors. Such errors occur when a calling program passes illegal parameters to an
intrinsic or does not have the required capability for the intrinsic. An abort error terminates
the process.
Condition Code Errors
Some intrinsics have an associated condition code. A condition code is a temporary value
providing information about what happened during execution. The condition code is aected
by many intrinsics and should be checked immediately upon return from an intrinsic.
A condition code has three possible values (CCG, CCL, or CCE) and has the general meaning
as indicated in Table 2-3. Specic meanings are listed under the individual intrinsic called.
Table 2-3. Condition Code Descriptions
Value
2-8
Condition Code
Description
0
CCG (>)
Condition Code Greater Than. A warning or special condition
occurred but may not have aected the execution of the request.
(For example, the request was executed, but default values were
assumed as intrinsic call parameters.)
1
CCL (<)
Condition Code Less Than. The request was not granted, but the
error condition may be recoverable.
2
CCE (=)
Condition Code Equal. Generally indicates that the request was
granted.
Intrinsic Use
Status Parameter Errors
Some intrinsics use the status parameter to return information on the status of the intrinsic
call. This parameter is a native mode (NM) implementation of the condition code feature
with extended capabilities. The status parameter is a 32-bit signed integer value passed by
reference.
Note
It is good programming practice to specify the status parameter and check its
value after an intrinsic call. If an error or warning condition is encountered
and the status parameter was not specied, the intrinsic causes the calling
process to abort.
The status parameter is read in two 16-bit elds:
Bits
16:16
0:16
Value/Meaning
status.subsys : identies the subsystem that initiated the error or warning.
status.info : identies the type of error or warning. Refer to each intrinsic
for possible values.
Table 2-4 and Table 2-5 represent the possible values returned by the status parameter.
Intrinsic Use
2-9
Table 2-4. Status.subsys Parameter Identifiers
Subsystem
ID
2-10
Subsystem
0
Successful (no errors)
9
CM Loader
098
System Aborts
100
Switch
101
Memory Manager
102
Process Manager
103
Stack Unwind
104
NM Loader
107
Virtual Space Management
108
Table Management
110
Clock/Timer Manager
111
High-Level I/O
113
Low-Level I/O
114
HP-IO Channel Manager
116
HP-IB Adapter Manager
121
CS80 Disk Manager
122
Port (IPC) Facility
123
Dispatcher
127
CIPER Device Manager
128
Terminal I/O Manager for Logging
130
Page Printer Device Manager
133
Measurement Interface
143
File System
145
Secondary Storage Management
151
Transaction Management
153
File System Label Management
154
CM Support Routines
155
Job and Session
Intrinsic Use
Table 2-4. Status.subsys Parameter Identifiers (continued)
Subsystem
ID
Subsystem
158
Break Handling
161
Command Interpreter
165
Debug Low-Level Breakpoint Management
169
CM Debugger
185
File System Storage Management
187
Error Management
188
CM Emulator, Translator, OCT
193
Floating-Point Conversion
195
Hewlett-Packard SORT
196
Hewlett-Packard MERGE
198
Eagle A-MUX Device Manager
200
U-Code Trap Handler
201
Data Communication Buer Manager
206
System Logging
213
I/O Services
221
Intrinsic Aborts
222
Intrinsic Names
Table 2-5. Status.info Parameter Identifiers
Value
0
<0
>0
Description
Normal
Indicates an error condition
Indicates a warning condition
Intrinsic Use
2-11
Abort Errors
Software traps are interrupts generated by software events in which the operating system
interrupts the normal ow of a process' execution. Some intrinsics generate a software trap
when they detect certain error conditions. Normally, if an intrinsic causes a trap, the system
trap handler aborts the user program. However, you can write a procedure to handle abort
errors and use it in place of the default system trap handler, which will permit recovery
from errors in certain cases. For more information on handling traps, refer to Trap Handling
Programmer's Guide (32650-90026).
When a program is aborted in a batch job, the operating system removes the job from the
system unless you precede the command that caused the error with a CONTINUE command.
If the program is aborted in an interactive session, the system returns control to the parent
process.
2-12
Intrinsic Use
Additional Capabilities Required
Most system intrinsics do not require additional capabilities to access operating system
features. However, if an intrinsic requires the operating system to check for an additional
capability at program load and/or run time, that capability must be assigned prior to running
the program.
Table 2-6 lists additional capabilities and the assignments required by some intrinsics.
Note
A system manager or account manager must assign the capabilities to the
group where the program le resides or to the user running the program. You
must assign PH, DS, MR, and PM capabilities to the program le at link time
using the caplist parameter of the LINK command.
Table 2-6. Additional Capabilities Required
Capability Required
Assignment To
Data segment management
(DS)
The program le and the group in which that le resides
User logging (LG)
The user running the program
Multiple RIN (MR)
The program le and the group in which that le resides
Nonshareable device (ND)
The user running the program
System supervisor (OP)
The user running the program
Process handling (PH)
The program le and the group in which that le resides
Privileged mode (PM)
The program le and the group in which that le resides
Programmatic sessions (PS)
The user running the program
Intrinsic Use
2-13
The operating system performs two capability checks prior to executing the program. The
checks must succeed before the program can run:
At load time, the le system checks the user capability list against the account-level,
group-level, and le-level security provisions for the program le and all referenced
executable library (XL) les.
At load time, the loader checks the program le's capability list against the capability list
for the group in which the program le resides. If the program is located in a temporary
le, the loader checks the program le's capability list against the capability list for the user
who is running the program. In this case, the capability must be assigned to the user in
addition to (or instead of) the group.
A third capability check occurs at run time when the program executes the code of an
intrinsic that requires a capability. The intrinsic checks either the program le (for DS, MR,
ND, PH, or PM) or the user (for LG, OP, or PS). If the operating system does not nd the
correct capability, the program aborts.
The operating system optional capabilities, and what they allow you to do, are explained
below.
DS Capability
The data segment management (DS) capability allows you to create and access extra data
segments from processes during a job or session.
LG Capability
The user logging (LG) capability provides a exible transaction-logging capability that allows
you to record additions and modications to your database and subsystem les on either tape
or disk. If the database is lost, the logging tape or disk le facilitates recovery of the lost
transactions.
MR Capability
The multiple resource identication number (MR) capability allows you to simultaneously lock
as many global resource identication numbers (RINs) as desired.
ND Capability
The nonshareable device (ND) capability allows you to use devices other than terminals, discs,
and spooled devices (except for the standard job/session input and list devices). If the device
is nonspooled, the user has absolute control of the device.
OP Capability
The system supervisor (OP) capability allows you to optimize the performance of the system
and to record additions and modications to your databases and subsystem les.
2-14
Intrinsic Use
PH Capability
The process handling (PH) capability allows you to do the following programmatically:
Create and delete processes
Activate and suspend processes
Send mail between processes
Change process scheduling
Get existing process information
PM Capability
The privileged mode (PM) capability allows you to access all operating system routines and
data structures. The operating system protects privileged users from executing at the same
privilege level as the operating system. This prevents privileged users from accessing certain
instructions used by the operating system to control the hardware. There are two ways to
acquire privileged mode:
If the routine should always run in privileged mode, use the execution-privilege option of the
appropriate compiler and designate the execution level as 2. (Refer to your programming
language reference manual for more details.)
If the routine requires privileged mode only on a selective basis, it is safer to obtain an
execution level of 2 only where necessary. To do this, invoke the GETPRIVMODE intrinsic.
Caution
The normal checks and limitations that apply to standard users are bypassed
in privileged mode. A privileged mode program can destroy le integrity and
the operating system software. Hewlett-Packard will 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 modication of the operating system software.
PS Capability
Programmatic sessions (PS) capability allows programmatic creation of sessions on any
terminal on the system.
Intrinsic Use
2-15
3
Intrinsic Tasks
This chapter is a quick reference for locating intrinsics that perform designated tasks.
Table 3-1 through Table 3-14 describe the general task, a subtask to the general task, and the
intrinsic associated with it. The general task is, in most cases, the title of a programmer's
guide and the subtasks correlate to chapters within that programmer's guide. For information
about the intrinsic specically, refer to chapter 4 of this manual. For information about the
use of an intrinsic, refer to the specied programmer's guide.
The tasks covered are:
Accessing Files (Table 3-1).
Accessing Command Interpreter Features (Table 3-2).
Getting System Information (Table 3-3).
Managing Processes (Table 3-4).
Managing Resources and System Information (Table 3-5).
Programming for Localization (Table 3-6).
Managing Message Catalogs (Table 3-7).
Converting Data Types (Table 3-8).
Sorting and Merging Data (Table 3-9).
Handling Traps (Table 3-10).
Managing Logging Facilities (Table 3-11).
Debugging Applications (Table 3-12).
Obtaining Device Information (Table 3-13)
Programming in Privileged mode (Table 3-14).
Managing USL Files (Table 3-15).
Managing Data Segments (Table 3-16).
Changing Stack Size (Table 3-17).
Using the Compiler Library (Table 3-18).
Programming Switch (Table 3-19).
Controlling Asynchronous Devices (Table 3-20).
Intrinsic Tasks
3-1
Table 3-1. Accessing Files
Function
Intrinsic
Manual
Opening a le
FOPEN
FPARSE
HPFOPEN
Accessing Files Programmer's
Guide (32650-90017)
Closing a File
FCLOSE
Accessing Files Programmer's
Guide (32650-90017)
Writing data to a le
FDEVICECONTROL
FSETMODE
FUPDATE
FWRITE
FWRITEDIR
FWRITELABEL
PRINT
PRINTOP
PRINTOPREPLY
Accessing Files Programmer's
Guide (32650-90017)
Reading data from a le
FREAD
FREADBACKWARD
FREADDIR
FREADSEEK
FSETMODE
READ
READX
Accessing Files Programmer's
Guide (32650-90017)
Controlling record pointer
movement
FCONTROL
FPOINT
FSPACE
Accessing Files Programmer's
Guide (32650-90017)
Accessing a mapped le
HPFOPEN
Accessing Files Programmer's
Guide (32650-90017)
Sharing a le
FOPEN
FLOCK
FUNLOCK
HPFOPEN
Accessing Files Programmer's
Guide (32650-90017)
Maintaining le security
FOPEN
HPFOPEN
Accessing Files Programmer's
Guide (32650-90017)
HPACDINFO
HPACDPUT
No manual
No manual
Getting le information
3-2
Intrinsic Tasks
FCHECK
FERRMSG
FFILEINFO
FGETINFO
FLABELINFO
FRELATE
FRENAME
Accessing Files Programmer's
Guide (32650-90017)
Accessing Files (Continued)
Function
Intrinsic
Manual
Error Checking
HPERRDEPTH
HPERRREAD
HPERRMSG
PRINTFILEINFO
Accessing Files Programmer's
Guide (32650-90017)
Accessing an RIO le
FOPEN
FDELETE
FREAD
FWRITE
HPFOPEN
Accessing Files Programmer's
Guide (32650-90017)
Table 3-2. Accessing Command Interpreter Features
Function
Intrinsic
Manual
Using commands
programmatically
COMMAND
HPCICOMMAND
Command Interpreter Access and
Variables Programmer's Guide
(32650-90011)
Controlling variables
HPCIDELETEVAR
HPCIGETVAR
HPCIPUTVAR
Command Interpreter Access and
Variables Programmer's Guide
(32650-90011)
Controlling job control words
(JCWs)
FINDJCW
GETJCW
PUTJCW
SETJCW
Command Interpreter Access and
Variables Programmer's Guide
(32650-90011)
Identifying Parameter Input
MYCOMMAND
SEARCH
Command Interpreter Access and
Variables Programmer's Guide
(32650-90011)
Intrinsic Tasks
3-3
Table 3-3. Getting System Information
Function
Intrinsic
Manual
Obtaining Time and Date
information
ALMANAC
CALENDAR
CLOCK
DATELINE
PROCTIME
TIMER
Getting System Information
Programmer's Guide (32650-90018)
Obtaining File information
FFILEINFO
FGETINFO
FLABELINFO
JOBINFO
WHO
Getting System Information
Programmer's Guide (32650-90018)
Formatting Time and Date
Information
FMTCALENDAR
FMTCLOCK
FMTDATE
Getting System Information
Programmer's Guide (32650-90018)
Error Checking
HPERRDEPTH
HPERRREAD
HPERRMSG
PRINTFILEINFO
Getting System Information
Programmer's Guide (32650-90018)
3-4
Intrinsic Tasks
Table 3-4. Managing Processes
Function
Intrinsic
Manual
Activating a Process
ACTIVATE
Interprocess Communication
Programmer's Guide (32650-90019)
Deactivating/Suspending a
Process
ABORTSESS
CAUSEBREAK
IODONTWAIT
IOWAIT
KILL
PAUSE
PROCINFO
PROCTIME
QUIT
QUITPROG
STARTSESS
SUSPEND
TERMINATE
Interprocess Communication
Programmer's Guide (32650-90019)
Creating a Process
CREATE
CREATEPROCESS
Interprocess Communication
Programmer's Guide (32650-90019)
Obtaining Process Information
FATHER
GETINFO
GETORIGIN
GETPRIORITY
GETPROCID
GETPROCINFO
JOBINFO
Interprocess Communication
Programmer's Guide (32650-90019)
Obtaining Mail Information
MAIL
RECEIVEMAIL
SENDMAIL
Interprocess Communication
Programmer's Guide (32650-90019)
Table 3-5. Managing Resources
Function
Intrinsic
Manual
Managing Global RINs
LOCKGLORIN
UNLOCKGLORIN
Resource Management
Programmer's Guide (32650-90024)
Managing Local RINs
FREELOCRIN
GETLOCRIN
LOCKLOCRIN
LOCRINOWNER
UNLOCKLOCRIN
Resource Management
Programmer's Guide (32650-90024)
HPFIRSTLIBRARY
HPGETPROCLABEL
HPMYFILE
HPMYPROGRAM
Resource Management
Programmer's Guide (32650-90024)
Intrinsic Tasks
3-5
Table 3-6. Programming for Localization
Function
Intrinsic
Manual
Retrieving information
ALMANAC
NLGETLANG
NLINFO
Native Language Programmer's
Guide (32650-90022)
Handling characters
NLCOLLATE
NLFINDSTR
NLJUDGE
NLKEYCOMPARE
Native Language Programmer's
Guide (32650-90022)
NLMATCH
NLMATCHINIT
NLREPCHAR
NLSCANMOVE
NLSUBSTR
NLSWITCHBUF
NLTRANSLATE
Formatting time and date
NLCONVCLOCK
NLCONVCUSTDATE
NLFMTCALENDAR
NLFMTCLOCK
NLFMTCUSTDATE
NLFMTDATE
NLFMTLONGCAL
Native Language Programmer's
Guide (32650-90022)
Formatting numbers
NLCONVNUM
NLFMTNUM
NLNUMSPEC
Native Language Programmer's
Guide (32650-90022)
Using application message
catalogs
CATCLOSE
CATOPEN
CATREAD
NLAPPEND
Native Language Programmer's
Guide (32650-90022)
Table 3-7. Managing Message Catalogs
Function
Intrinsic
CATCLOSE
CATOPEN
CATREAD
GENMESSAGE
3-6
Intrinsic Tasks
Manual
Message Catalogs Programmer's
Guide (32650-90021)
Table 3-8. Converting Data Types
Function
Intrinsic
Manual
Converting binary numbers
ASCII
DASCII
Data Types Conversion
Programmer's Guide (32650-90015)
Converting numeric ASCII
strings
BINARY
DBINARY
Data Types Conversion
Programmer's Guide (32650-90015)
Translating ASCII/EBCDIC or
JISCII/EBCDIK
CTRANSLATE
Data Types Conversion
Programmer's Guide (32650-90015)
Converting oating-point
formats
HPFPCONVERT
Data Types Conversion
Programmer's Guide (32650-90015)
Table 3-9. Sorting and Merging Data
Function
Intrinsic
Manual
Creating core merge routines
(NM)
HPMERGEEND
HPMERGEERRORMESS
HPMERGEINIT
HPMERGEOUTPUT
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Creating core merge routines
(CM)
MERGEEND
MERGEERRORMESS
MERGEINIT
MERGEOUTPUT
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Getting merge information (NM) HPMERGESTAT
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Getting merge information (CM) MERGESTAT
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Creating core sort routines (NM) HPSORTEND
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Creating core sort routines (CM) SORTEND
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Getting sort information (NM)
HPSORTSTAT
HPSORTTITLE
SORT-MERGE/XL Programmer's
Guide (32650-90080)
Getting sort information (CM)
SORTSTAT
SORTTITLE
SORT-MERGE/XL Programmer's
Guide (32650-90080)
HPMERGETITLE
MERGETITLE
HPSORTERRORMESS
HPSORTINIT
HPSORTINPUT
HPSORTOUTPUT
SORTERRORMESS
SORTINIT
SORTINPUT
SORTOUTPUT
Intrinsic Tasks
3-7
Table 3-10. Handling Traps
Function
Intrinsic
ARITRAP
FINTEXIT
FINSTATE
HPENABLTRAP
RESETCONTROL
XARITRAP
XCONTRAP
XLIBTRAP
XSYSTRAP
Manual
Trap Handling Programmer's Guide
(32650-90026)
Table 3-11. Managing Logging Facilities
Function
Intrinsic
Manual
Marking a logical transaction
BEGINLOG
ENDLOG
User Logging Programmer's Guide
(32650-90027)
Closing a log le
CLOSELOG
User Logging Programmer's Guide
(32650-90027)
Flushing the logging buer
FLUSHLOG
User Logging Programmer's Guide
(32650-90027)
Getting information from the
log le
LOGINFO
LOGSTATUS
User Logging Programmer's Guide
(32650-90027)
Opening a log le
OPENLOG
User Logging Programmer's Guide
(32650-90027)
Writing to a log le
WRITELOG
User Logging Programmer's Guide
(32650-90027)
Table 3-12. Debugging Applications
Function
Intrinsic
Manual
Entering the debug facility
DEBUG
HPDEBUG
MPE/iX System Debug Reference
Manual (32650-90013)
Disarming a debug call
HPRESETDUMP
RESETDUMP
MPE/iX System Debug Reference
Manual (32650-90013)
Arming a debug call
HPSETDUMP
SETDUMP
MPE/iX System Debug Reference
Manual (32650-90013)
Producing a full stack trace
STACKDUMP
MPE/iX System Debug Reference
Manual (32650-90013)
3-8
Intrinsic Tasks
Table 3-13. Obtaining Device Information
Function
Intrinsic
Obtaining volume information
HPVOLINFO
Accessing peripheral
functionality
HPDEVCONTROL
Manual
Table 3-14. Programming in Privileged mode
Function
Intrinsic
Manual
Starting privileged mode
GETPRIVMODE
Introduction to MPE XL for MPE
V Programmers (30367-90005)
Ending privileged mode
GETUSERMODE
Introduction to MPE XL for MPE
V Programmers (30367-90005)
Table 3-15. Managing USL Files
Function
Intrinsic
Manual
Changing USL les
ADJUSTUSLF
EXPANDUSLF
MPE Segmenter Reference Manual
(30000-90011)
Creating USL les
CLEANUSL
MPE Segmenter Reference Manual
(30000-90011)
Initializing USL les
INITUSLF
MPE Segmenter Reference Manual
(30000-90011)
Table 3-16. Managing Data Segments
Function
Intrinsic
Manual
Introduction to MPE XL for MPE
V Programmers (30367-90005)
ALTDSEG
DMOVIN
DMOVOUT
FREEDSEG
GETDSEG
SWITCHDB
Table 3-17. Changing Stack Size
Function
Changing the stack size
Intrinsic
DLSIZE
ZSIZE
Manual
Introduction to MPE XL for MPE
V Programmers (30367-90005)
Intrinsic Tasks
3-9
Table 3-18. Using the Compiler Library
Function
Intrinsic
Manual
Compiler Library/XL Reference
Manual (32650-90029)
Table 3-19. Programming Switch
Function
Intrinsic
Manual
Loading a CM procedure
HPLOADCMPROCEDURE
LOADPROC
Switch Programming Guide
(32650-90014)
Unloading a CM procedure
HPUNLOADCMPROCEDURE
UNLOADPROC
Switch Programming Guide
(32650-90014)
Loading a NM procedure
HPLOADNMPLABEL
Switch Programming Guide
(32650-90014)
Switching from CM to NM
HPSWTONMNAME
HPSWTONMPLABEL
Switch Programming Guide
(32650-90014)
Switching from NM to CM
HPSWITCHTOCM
HPSETCCODE
Switch Programming Guide
(32650-90014)
3-10
Intrinsic Tasks
Table 3-20. Controlling Asynchronous Devices
Function
Intrinsic
Manual
Controlling system breaks
FCONTROL
CAUSEBREAK
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Controlling subsystem breaks
FCONTROL
XCONTRAP
RESETCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Specifying carriage control
directives
FCONTROL
FWRITE
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Specifying an EOR character
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Enabling/Disabling echo
FCONTROL
FSETMODE
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Specifying line deletion echo
response
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Setting editing mode
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Setting transmission mode
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Specifying and enabling parity
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Specifying terminal type
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Setting a read timeout
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Timing a read
FCONTROL
MPE XL Asynchronous Serial
Communications Programmer's
Reference Manual (32022-90012)
Intrinsic Tasks
3-11
4
Command Definitions
This chapter describes MPE/iX intrinsics, arranged alphabetically.
Throughout this chapter, paragraphs beginning with the following acronyms should be
interpreted as follows:
(NM)
For use in native mode programming only.
(CM)
For use in compatibility mode programming only.
(KSAM)
For use with KSAM les only.
(ASC)
For use with asynchronous serial communications only.
(SPL)
For use with SPL programming language only.
Command Definitions
4-1
ABORTSESS
NM and CM callable.
Enables a program to abort a specied job or session from the system.
Syntax
I16V I32V I16A
ABORTSESS(jsid,jsnum,jsstatus);
Parameters
jsid
16-bit signed integer by value (required)
Indicates whether the jsnum parameter refers to a job number or a session
number:
Value
1
2
Meaning
Session number
Job number
jsnum
Because jobs and sessions can have identical numbers, the jsid parameter is
required to indicate whether jsnum describes a job or a session.
32-bit signed integer by value (required)
jsstatus
Passes the job or session number of the job/session to be aborted.
16-bit signed integer array (required)
Returns a two-element array containing status information. The second
element is reserved for the operating system. The rst element returns one of
the following status values:
Value
0
1
2
3
4-2
Command Definitions
Meaning
Successful
Jobsecurity set to high, or job/session not yours
Job/session does not exist
Job/session being introduced and cannot be aborted when in
the INTRO state
ABORTSESS
Operation Notes
All resources held by the aborted job/session are released, and any I/O activity is terminated.
Although the job/session is abnormally terminated, the operating system issues log records
and updates CPU and connect times. The following message is displayed on the job/session
list device:
SESSION ABORTED BY SYSTEM MANAGEMENT
ABORTSESS can be applied to waiting or scheduled jobs, or executing jobs or sessions. If the
spooler input le ($STDIN) for a batch job has been created and has not yet been opened, the
entire le is deleted. If ABORTSESS is issued before the output spoolle is complete, only that
portion of the le already opened is printed and an error message is issued indicating that the
job was aborted.
ABORTSESS can be successfully called only if the program is executing in a job/session that
satises at least one of the following conditions:
The job/session is on the system console.
The job/session was allowed the ABORTJOB command.
JOBSECURITY is set to LOW and the user and account names of the job/session are the same
as the user and account names of the job/session being aborted.
JOBSECURITY is set to LOW and the job/session has account manager (AM) capability, and
the account name of the job/session is the same as the account name of the job/session
being aborted.
JOBSECURITY is set to LOW and the job/session has system manager (SM) capability.
Related Information
Intrinsics
Commands
Manuals
STARTSESS
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-3
ACTIVATE
NM and CM callable.
Activates a newly created process, or a process suspended with the SUSPEND intrinsic.
Requires process handling (PH) capability.
Syntax
I16V U16V
ACTIVATE(pin,allow);
Parameters
pin
16-bit signed integer by value (required)
allow
Indicates the parent or child process to be activated. To indicate a parent
process, set pin to zero. To indicate a child process, set pin to the process
identication number (PIN) of the process. The called process must always
be expecting an activation from the caller (refer to the SUSPEND and CREATE
intrinsics).
16-bit unsigned integer by value (optional)
Passes suspend or execute information to the process being activated:
When allow is not specied or is zero, the called process is activated by the
operating system but does not commence execution immediately. Instead,
control returns to the calling process, which continues execution. This is the
default.
When allow is specied and is not zero, the calling process is suspended
while the called process is activated and commences execution. Bits (14:2)
specify the anticipated source of the call that reactivates the calling process:
Bits
Value/Meaning
15:1
Parent activation bit:
0 Does not expect activation by a parent
1 Expects activation by a parent
14:1
Child activation bit:
0 Does not expect activation by a child
1 Expects activation by one child
0:14
4-4
Command Definitions
Reserved for the operating system
ACTIVATE
Operation Notes
A newly created process can only be activated by its parent. A suspended process can be
reactivated by its parent, or any of its children, as specied in the allow parameter of the
ACTIVATE and SUSPEND intrinsics. When a process is activated, it runs until it is either
suspended or deleted.
The ACTIVATE intrinsic aborts the calling process (and possibly the entire job/session) if a
request to activate the parent results in the activation of the root CI or a system process. The
abort error messages associated with these situations are:
ACTIVATION OF SYSTEM PROCESS NOT ALLOWED
(ACTIVATE ERROR 20)
ACTIVATION OF MAIN PROCESS NOT ALLOWED
(ACTIVATE ERROR 21)
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The called process is activated. The calling process is
suspended if you specied allow .
Request granted. The called process is already active. The calling process is
suspended if you specied allow .
Request denied. The called process was not expecting activation by this
calling process, an illegal pin parameter was specied, or the allow parameter
was specied improperly.
Related Information
Intrinsics
Commands
Manuals
CREATE, SUSPEND
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-5
ADJUSTUSLF
NM and CM callable.
Adjusts directory space in a USL le by moving the start of the information block forward (or
backward) on a user subprogram library (USL) le, thereby increasing (or decreasing) the
space available for the le directory block. The overall length of the le does not change. This
intrinsic is intended for programmers writing compilers.
Note
A USL contains CM object code and is meaningful only in the CM program
development process.
Syntax
I16
I16V
I16V
uslferror:=ADJUSTUSLF(uslfnum,adjustment);
Functional Return
uslferror
16-bit signed integer (assigned functional return)
Returns the error number if an error occurs (condition code returns CCL
(1)). If no error occurs, no value is returned. The error number returned
corresponds to the following:
Value
0
1
4
5
6
4-6
Command Definitions
Meaning
The le specied by uslfnum was empty, an unexpected
end-of-le was encountered while reading the uslfnum , or an
unexpected end-of-le was encountered while writing the
uslfnum .
Unexpected I/O error occurred.
Request exceeds the maximum le directory size (32,768 half
words).
Insucient directory space.
Insucient USL le information block space.
ADJUSTUSLF
Parameters
uslfnum
16-bit signed integer by value (required)
increment
Passes the le number of the USL le (returned by FOPEN/HPFOPEN).
16-bit signed integer by value (required)
Returns the assigned record count:
If a positive value, the information block is moved toward the end-of-le in
the USL le, increasing the directory block and decreasing the information
block.
If a negative value, the information block is moved toward the start of the
USL le, decreasing the directory block and increasing the information
block.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error number was returned to uslferror indicating the
reason for this failure.
Related Information
Intrinsics
Commands
Manuals
CLEANUSL, EXPANDUSLF, INITUSLF
None
MPE Segmenter Reference Manual (30000-90011)
Command Definitions
4-7
ALMANAC
NM and CM callable.
Returns the numeric date information for a date returned by the CALENDAR intrinsic. The
returned information is year of century, month of year, day of month, and day of week.
Syntax
U16V U16A
I16
I16
ALMANAC(date,daterror,yearnum,monthnum,
I16
I16
daynum,weekdaynum);
Parameters
date
16-bit unsigned integer by value (required)
Contains the date in the following format:
daterror
Bits
Value/Meaning
7:9
0:7
Day of year
Year of century
16-bit unsigned integer array (required)
Returns two elements; the rst element is the error number, the second
element is reserved and always returns 0. The possible error numbers returned
are:
Value
0
1
2
3
Meaning
Successful
No parameters available for returning values
Day of year out of range
Year of century out of range
yearnum
16-bit signed integer by reference (optional)
monthnum
Returns the year of century. For example, 00=1900, 84=1984.
16-bit signed integer by reference (optional)
daynum
Returns the month of year. For example, 1=January, 12=December.
16-bit signed integer by reference (optional)
Returns the day of month.
4-8
Command Definitions
ALMANAC
weekdaynum
16-bit signed integer by reference (optional)
Returns the day of week. For example, 1=Sunday, 7=Saturday.
Related Information
Intrinsics
Commands
Manuals
CALENDAR, CLOCK, FMTCALENDAR, FMTCLOCK, FMTDATE
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-9
ALTDSEG
NM and CM callable.
Reduces the storage required by the extra data segment when moved into main memory
and expands storage as required, allowing for a more ecient use of memory. Data segment
management (DS) capability is required.
Data segment management (DS) intrinsics are not recommended for use in the
operating system native mode programming environment; use of DS intrinsics
degrade program performance.
Note
Syntax
U16V I16V
I16
ALTDSEG(index,increment,size);
Parameters
index
16-bit unsigned integer by value (required)
increment
Indicates the index of the extra data segment, obtained from the GETDSEG call.
16-bit signed integer by value (required)
size
Species the value, in half words, the extra data segment is to be changed. A
positive value requests an increase; a negative value requests a decrease.
16-bit signed integer by reference (required)
Returns the new size of the extra data segment after incrementing or
decrementing has occurred.
4-10
Command Definitions
ALTDSEG
Operation Notes
Incrementation and decrementation is accomplished in even multiples of four half words,
which are rounded up. For example (in half words):
Present Segment Size
Change Value
New Segment Size
128
128
128
128
128
-3
-4
+1
+3
+4
128
124
132
132
132
When a data segment is created through GETDSEG, the required virtual space is allocated by
the system to accommodate the original length of the data segment. This virtual space is
allocated in increments of 512 half words. For example, creation of an extra data segment
with a length of 600 half words results in the allocation of 1024 half words of virtual space.
Note
ALTDSEG cannot increase the size of a data segment to exceed the virtual space
originally allocated through GETDSEG.
When GETDSEG is called in privileged mode, the ALTDSEG intrinsic must also be called in
privileged mode.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request granted. An illegal decrement was requested to a total segment size
of <=0; the current size remains in aect. An illegal increment was requested
for a total segment size greater than the virtual space originally assigned; the
size of the virtual space is granted and returned to the size parameter.
Request denied. An illegal index parameter was specied.
Additional Discussion
Intrinsics
Commands
Manuals
FREEDSEG, GETDSEG
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
4-11
ARITRAP
NM and CM callable (dierences noted below).
Collectively enables all arithmetic traps (except the IEEE inexact result trap) or disables all
arithmetic traps.
Syntax
I*V
ARITRAP(trapstate);
Parameters
trapstate
(NM)32-bit signed integer by value (required)
(CM)16-bit signed integer by value (required)
(NM) Enables/disables arithmetic traps:
Value
0
1
Meaning
Disable all arithmetic traps
Enable all arithmetic traps (except the IEEE inexact result
trap)
(CM) Enables/disables CM arithmetic traps.
Operation Notes
There is a dierence between arming and enabling traps. Enabling a trap means that the
occurrence of a trap condition is not ignored. Arming a trap is required so that, on a trap
condition, a user-written routine is invoked and can take appropriate recovery actions. The
following list summarizes what can happen when an arithmetic trap condition occurs:
If a trap is both enabled and armed, the user-written trap handler is invoked.
If a trap is enabled but not armed, one of two situations apply:
If a Pascal/XL TRY statement was executed, pass control to the RECOVER block by
doing an ESCAPE.
If a Pascal/XL TRY statement was not executed, an error message is output and the
process aborts.
If a trap is disabled, even though it is armed, the trap is ignored, and execution of the
process continues without any interruption.
Note
4-12
By default, all traps (except the IEEE inexact result trap) are enabled and the
system trap handler is armed.
Command Definitions
ARITRAP
(NM) The possible interrupts listed below are collectively called the arithmetic traps:
3000 mode double-precision divide by zero
3000 mode double-precision overow
3000 mode double-precision underow
3000 mode oating-point divide by zero
3000 mode oating-point overow
3000 mode oating-point underow
3000 mode packed decimal error
Decimal divide by zero
Decimal overow
IEEE oating-point divide by zero
IEEE oating-point underow
IEEE oating-point overow
IEEE oating-point, invalid operation
Integer divide by zero
Integer overow
Invalid ASCII digit
Invalid decimal digit
Paragraph stack overow
Range errors
Result of software-detected pointer arithmetic misaligned or error in conversion from long
pointer to short pointer
Software-detected NIL pointer reference
Unimplemented condition traps
Note
The IEEE inexact result trap is not enabled by ARITRAP.
(CM) The possible interrupts listed below are collectively called the arithmetic traps:
3000 mode double-precision divide by zero
3000 mode double-precision overow
3000 mode double-precision underow
3000 mode oating-point divide by zero
3000 mode oating-point overow
3000 mode oating-point underow
Decimal divide by zero
Decimal overow
Integer divide by zero
Integer overow
Invalid ASCII digit
Invalid decimal digit
Invalid decimal operand length
Invalid source word count
Command Definitions
4-13
ARITRAP
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. All arithmetic traps were originally disabled.
Request granted. At least one arithmetic trap was originally enabled.
Not returned.
Related Information
Intrinsics
Commands
Manuals
4-14
XARITRAP
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
ASCII
ASCII
NM and CM callable.
Converts a 16-bit binary number to a specied base and represents it as a numeric ASCII
string.
Syntax
I16
*
I16V
CA
numchar:=ASCII(binvalue,base,asciieqv);
Functional Return
numchar
16-bit signed integer (assigned functional return)
Returns the number of characters in the resulting ASCII equivalent.
Parameters
binvalue
type varies by value (required)
base
Passes the binary number to be converted to an ASCII string:
For octal conversions, binvalue must be a 16-bit unsigned integer.
For decimal conversions, binvalue must be a 16-bit signed integer.
For hexadecimal conversions, binvalue must be a 16-bit unsigned integer
16-bit signed integer by value (required)
Passes and must be one of the following values or the process aborts:
Value
8
10
-10
16
asciieqv
Meaning
Convert to octal (pad with zeros)
Convert to decimal (left-justify)
Convert to decimal (right-justify)
Convert to hexadecimal (pad with zeros)
character array (required)
Returns the converted value. Must be long enough to contain the result (<=
6 characters):
For octal conversions (base=8), 6 characters (including leading zeros)
are returned; numchar returns the number of signicant (right-justied)
characters (excluding leading zeros). If binvalue=0, the length returned is
1.
Command Definitions
4-15
ASCII
For decimal conversions, binvalue is considered a 16-bit, twos complement
integer ranging from -32768 to +32767. If binvalue=0, only one zero
character is returned in asciieqv; numchar returns the total number of
characters (including the sign). For example, if binvalue=0, the length
returned is 1; and if binvalue=327, the length returned is 3.
For decimal left-justied conversions (base=10), leading zeros are removed,
and the numeric ASCII result is left-justied in asciieqv; the most
signicant digit (or the "-" sign) is in asciieqv(1), the next most signicant
digit is in asciieqv(2), and so on.
For decimal right-justied conversions (base=-10), the result is
right-justied in asciieqv; the least signicant digit is in asciieqv(-1), the
next least signicant digit is in asciieqv(-2), and so on.
For right-justied conversions, the character array where the converted
value is to be placed must specify the rightmost byte where data is placed.
For example, if asciieqv is a 10 byte array declared as:
VAR
MYSTRING : ARRAY [1..10] OF CHAR;
then you must specify it in the ASCII intrinsic call as follows (for right
justication):
NUMCHAR:=ASCII(VALUE,-10&
,WADDRESS(MYSTRING[10]));
The result is right-justied in asciieqv, with the rightmost digit of the
result contained in the last (rightmost) byte of asciieqv.
For hexadecimal conversions (base=16), 4 characters (including leading
zeros) are returned. The digits can be 0..9 and A..F.Numchar returns the
number of signicant (right-justied) characters (excluding leading zeros).
For example, if binvalue=32, numchar is 2 and asciiqv will be 0020.
For all right-justied conversions asciieqv must be initialized to blanks before
the call is made.
Note
Related Information
Intrinsics
Commands
Manuals
4-16
DASCII, BINARY, DBINARY
None
Data Types Conversion Programmer's Guide (32650-90015)
Command Definitions
BEGINLOG
BEGINLOG
NM and CM callable.
Posts a special record to the user logging le to mark the beginning of a logical transaction.
When BEGINLOG is called, the logging memory buer is ushed to ensure that the record gets
to the logging le. User logging (LG) or system supervisor (OP) capability is required.
Syntax
I32 U16A I16
I16
I16
BEGINLOG(index,data,length,mode,logstatus)
Parameters
index
32-bit signed integer by reference (required)
data
Passes access information to the user logging system. This is the value
returned in the index parameter of the OPENLOG intrinsic.
16-bit unsigned integer array (required)
length
Passes the information to be logged. A log record contains 128 half words
where 119 are available for writing data. For the most ecient use of log le
space, structure arrays with lengths in multiples of 119 half words.
16-bit signed integer by reference (required)
mode
Passes the length of the data. A positive value indicates half words; a
negative value indicates bytes. If the length is greater than 119 half words (or
238 bytes), the information in data is divided into two or more physical log
records.
16-bit signed integer by reference (required)
Passes a value indicating whether the logging process should suspend the
process if it cannot complete the request for service immediately. If it is not
possible to log the transaction and mode is set to nowait, the BEGINLOG
intrinsic indicates, through logstatus, that it could not complete the request:
Value
Meaning
0
1
Wait
Nowait
Command Definitions
4-17
BEGINLOG
logstatus
16-bit signed integer by reference (required)
Returns a value, indicating the success/failure of the intrinsic call:
Value
0
1
2
4
5
9
12
14
15
Meaning
Successful
Nowait mode requested, and user logging process is busy
Parameter out of bounds
Incorrect index parameter passed
Incorrect mode parameter passed
Error occurred while writing
System out of disk space, user logging cannot proceed
Invalid access
End-of-le
Operation Notes
Use the data parameter of this intrinsic to post user data to the logging le. This use of
BEGINLOG is similar to using the WRITELOG intrinsic, but also denotes the beginning of a logical
transaction.
Related Information
Intrinsics
Commands
Manuals
4-18
ENDLOG, WRITELOG
None
User Logging Programmer's Guide (32650-90027)
Command Definitions
BINARY
BINARY
NM and CM callable.
Converts a numeric (octal or decimal) ASCII string to a 16-bit twos complement binary value.
Syntax
I16
CA
I16V
bineqv:=BINARY(asciieqv,length);
Functional Return
bineqv
16-bit signed integer (assigned functional return)
Passes the twos complement binary equivalent of the numeric string.
Parameters
asciieqv
character array (required)
length
Passes the octal or signed-decimal number (in ASCII characters) to be
converted. If the character string begins with a percent sign (%), it is treated
as an octal value. If the character string begins with a dollar sign ($), it is
treated as a hexadecimal value. In this case, the string must be less than 6
characters and only 0 through 9, a through f, and A through F are allowed. If
the character string begins with a plus sign, a minus sign, or a number, it is
treated as a decimal value. Leading blanks are not allowed and are treated as
illegal characters.
16-bit signed integer by value (required)
Passes the length (number of bytes) of the ASCII-coded value. If the value of
length is 0, the intrinsic returns 0 to the calling process. When the value of
length is negative, the intrinsic causes the process to abort.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. A 16-bit binary value is returned to the process.
Request denied. A word overow, possibly resulting from too many characters
(asciieqv number too large), occurred in the value returned.
Request denied. An illegal character was encountered in asciieqv. For
example, the digits 8 or 9 were specied in an octal value.
Command Definitions
4-19
BINARY
Related Information
Intrinsics
Commands
Manuals
4-20
DBINARY
None
Data Types Conversion Programmer's Guide (32650-90015)
Command Definitions
CALENDAR
CALENDAR
NM and CM callable.
Returns the calendar date, including the day of year and the year of century.
Syntax
U16
date:=CALENDAR;
Functional Return
date
16-bit unsigned integer (assigned functional return)
Returns the calendar date in the following format:
Bits
7:9
0:7
Value/Meaning
Day of year
Year of century
Related Information
Intrinsics
Commands
Manuals
ALMANAC
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
4-21
CATCLOSE
NM and CM callable.
Closes an application message catalog that was opened with CATOPEN.
Syntax
I32V
U16A
CATCLOSE(catindex,catstatus)
Parameters
catindex
32-bit signed integer by value (required)
catstatus
Passes the catalog index returned by the CATOPEN intrinsic.
16-bit unsigned integer array (required)
Returns two elements; the rst element is the error number, the second
element is reserved and always returns 0. The possible values of the rst
element returned are:
Value
0
1
100
Meaning
Successful
Close of catalog le failed
Internal message facility error
Related Information
Intrinsics
Commands
Manuals
4-22
CATOPEN, CATREAD
None
Message Catalogs Programmer's Guide (32650-90021)
Command Definitions
CATOPEN
CATOPEN
NM and CM callable.
Opens an application message catalog that was formatted with the GENCAT utility. CATOPEN
returns a value that identies the catalog and is used by CATREAD and CATCLOSE.
Syntax
I32
CA
U16A
catindex:=CATOPEN(formaldesig,catstatus);
Functional Return
catindex
32-bit signed integer (assigned functional return)
An internal value recognized by the CATREAD and CATCLOSE intrinsics.
Note
The functional return is not a le number.
Parameters
formaldesig
character array (required)
Passes a string of ASCII characters that identify the catalog le to the
system. This string must be terminated by an ASCII special character, it
does not accept \/", \.", \:", or \!" as terminators.
catstatus
formaldesig does not accept \/", \.", \:", or \!"
as terminators.
16-bit unsigned integer array (required)
Returns two elements; the rst element is the error number, the second
element is reserved and always returns 0. The possible values of the rst
element returned are:
Value
0
1
2
3
100
Meaning
Successful
Open failed on catalog le
Could not access catalog le
File specied not a GENCAT formatted catalog
Internal message facility error
Command Definitions
4-23
CATOPEN
Operation Notes
The CATOPEN intrinsic may alter the condition code (CCODE).
Related Information
Intrinsics
Commands
Manuals
4-24
CATCLOSE, CATREAD
None
Message Catalogs Programmer's Guide (32650-90021)
Command Definitions
CATREAD
CATREAD
NM and CM callable.
Provides access to messages in an application message facility formatted by the GENCAT
utility. The CATOPEN intrinsic opens the message catalog.
Syntax
I16
I32V
I16V
U16A
CA
I16V
msglength:=CATREAD(catindex,setnum,msgnum,
I16V
catstatus,buer,buersize,
CA
CA
CA
CA
CA
parm1,parm2,parm3,parm4,parm5,
I16V
msgdest);
Functional Return
msglength
16-bit signed integer (assigned functional return)
Returns the length of the message (in bytes).
Parameters
catindex
32-bit signed integer by value (required)
setnum
Passes the index (returned by the CATOPEN intrinsic) that species the
message catalog to be used. The message catalog must have been formatted
with the GENCAT utility.
16-bit signed integer by value (required)
msgnum
Passes the message set number within the catalog (1..255).
16-bit signed integer by value (required)
Passes the message number within the message set (0..32,766).
Command Definitions
4-25
CATREAD
catstatus
16-bit unsigned integer array (required)
Returns two elements; the rst element is the error number, the second
element is reserved and always returns 0. The possible values of the rst
element returned are:
Value
0
1
2
3
4
6
7
14
15
16
17
18
19
100
Meaning
Successful
Invalid catindex specied
Read failed on catalog le
Message set not found
Message number not found
User buer overow
Write to msgdest le failed
setnum <= 0 specied
setnum > 255 specied
msgnum < 0 specied
msgnum > 32,766 specied
buersize <= 0 specied
msgdest <= -2 specied
Internal message facility error
buer
character array (optional)
buersize
Returns the assembled message.
16-bit signed integer by value (optional)
Passes the buer length in bytes if you specify buer . Passes the length (in
bytes) of the message to be written to the destination le if buer is not
specied.
parm1-parm5
Default = 72 bytes.
character arrays (optional)
Passes parameters to be inserted into the message. The parameter must
always point to a character string and the character string must be
terminated by a binary zero.
4-26
Command Definitions
CATREAD
msgdest
16-bit signed integer by value (optional)
Passes the le number of the message's destination le (0 or -1 = $STDLIST,
>2 = le number of the destination le). If buer or msgdest are not
specied, the message goes to $STDLIST ($STDLIST = 0).
Operation Notes
The combined total size of the buer and parm1 through parm5 parameters cannot exceed
64,000 bytes.
Related Information
Intrinsics
Commands
Manuals
CATCLOSE, CATOPEN
None
Message Catalogs Programmer's Guide (32650-90021)
Command Definitions
4-27
CAUSEBREAK
NM and CM callable.
Interrupts the program (the entire process structure). The CAUSEBREAK intrinsic is the
programmatic equivalent to pressing 4Break5 in a session, and is not applicable in jobs. The
program is suspended while in break mode. Execution of the program can resume where the
interruption occurred by entering the RESUME command, or be aborted by entering the ABORT
command.
Syntax
CAUSEBREAK;
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The intrinsic was not called from an interactive session.
Related Information
Intrinsics
Commands
Manuals
4-28
None
ABORT, RESUME
Process Management Programmer's Guide (32650-90023)
Command Definitions
CLEANUSL
CLEANUSL
NM and CM callable.
Deletes all inactive entries from currently managed USL les and returns the le number of
the new USL le. Therefore, you must test the condition code immediately upon return from
the intrinsic. Unpredictable results occur if an error number is used as a le number.
Note
A USL contains CM object code and is meaningful in the CM program
development process only.
Syntax
I16
I16V
CA
lenum:=CLEANUSL(uslfnum,formaldesig);
Functional Return
lenum
16-bit signed integer (assigned functional return)
Returns the new le number, if no error occurs, or if an error occurs condition
code returns CCL (1) and lenum returns one of the following:
Value
0
1
7
12
Meaning
Unexpected end-of-le (EOF) marker on either the old or the
new USL le
Unexpected I/O error on either the old or the new USL le
Unable to open new USL le
Invalid USL le
Parameters
uslfnum
16-bit signed integer by value (required)
formaldesig
Returns the le number of the le.
character array (required)
Passes the name to be given to the cleaned le. The array must end with a
blank. If it contains all blanks, it deletes the inactive entries.
Command Definitions
4-29
CLEANUSL
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The new le number is returned to lenum .
Not returned.
Request denied. An error number is returned to lenum .
Related Information
Intrinsics
Commands
Manuals
4-30
ADJUSTUSLF, EXPANDUSLF, INITUSLF
None
MPE Segmenter Reference Manual (30000-90011)
Command Definitions
CLOCK
CLOCK
NM and CM callable.
Returns the time (hours, minutes, seconds, and tenths of seconds) according to the system
timer.
Syntax
I32
time:=CLOCK;
Functional Return
time
32-bit signed integer (assigned functional return)
Returns the time, as monitored by the system timer, in the following format:
Bits
24:8
16:8
8:8
0:8
Value/Meaning
Tenths of seconds
Seconds
Minute of hour
Hour of day
Related Information
Intrinsics
Commands
Manuals
None
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
4-31
CLOSELOG
NM and CM callable.
Closes access to the user logging facility. User logging (LG) or system supervisor (OP)
capabilities are required.
Syntax
I32 I16
I16
CLOSELOG(index,mode,logstatus);
Parameters
index
32-bit signed integer by reference (required)
mode
Passes access capabilities to the user logging system. This is the value
returned in the index parameter of the OPENLOG intrinsic.
16-bit signed integer by reference (required)
Passes a value, indicating whether the user logging facility should suspend the
process if it cannot complete the request for service immediately:
logstatus
Value
Meaning
0
1
Wait
Nowait
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the
intrinsic call:
Value
0
1
4
5
7
9
12
14
15
4-32
Command Definitions
Meaning
Successful
Nowait mode requested; user logging process busy
Incorrect index parameter passed
Incorrect mode parameter passed
Illegal capability; user logging (LG) or system supervisor (OP)
capabilities required
Error occurred while writing
System out of disk space; user logging cannot proceed
Invalid access to user logging le
End-of-le encountered
CLOSELOG
Operation Notes
The number of users and log entries are independent of the number of times the
OPENLOG/CLOSELOG intrinsics are called within an application. The user logging facility
establishes a logging buer (LOGBUFF) entry and increments the user count only at the rst
OPENLOG call. Another counter keeps track of the number of times OPENLOG and CLOSELOG are
called. The counter is incremented for every OPENLOG and decremented for every CLOSELOG.
This ensures that the entry in LOGBUFF is released only for the last CLOSELOG call (call counter
= 0).
Related Information
Intrinsics
Commands
Manuals
OPENLOG
None
User Logging Programmer's Guide (32650-90027)
Command Definitions
4-33
COMMAND
NM and CM callable.
Programmatically executes a command.
Syntax
CA
I16
I16
COMMAND(cmdimage,cmderror,parmnum);
Parameters
cmdimage
cmderror
character array (required)
Passes an ASCII string of <=279 characters consisting of a command and
parameters, terminated by a carriage return. The carriage return character
(%15) must be the last character of the command string. Do not include a
prompt character in this string.
16-bit signed integer by reference (required)
Returns any error code set by the command:
If cmderror is zero, no error occurred.
If cmderror is negative, a warning was detected.
This the same error that would be returned by the command interpreter if
cmdimage were executed interactively or in batch. The error message can be
found in message set two of CATALOG.PUB.SYS.
Note
When the CI displays multiple errors for a single command, cmderror
contains only the last error number displayed.
Note
Remote commands executed through the COMMAND or HPCICOMMAND
intrinsics may not return a meaningful error status.
parmnum
16-bit signed integer by reference (required)
Returns a number indicating the error:
If parmnum is positive, it is a le system error number and cmderror is
non-zero.
If parmnum is negative, it is the column number where the error occurred
and cmderror is non-zero. (The command interpreter (CI) prints a caret
there.)
If parmnum is zero, then no additional error-related data is available.
4-34
Command Definitions
COMMAND
Note
The cmderror is the correct parameter to check to verify if cmdimage
succeeded. The parmnum may provide additional information.
Operation Notes
User-dened commands (UDCs) cannot be executed with the COMMAND intrinsic. RUN and
other process creation commands are allowed if you, or the program calling COMMAND, have
process handling (PH) capability. Command les and the implied RUN are not allowed.
The cmdimage parameter can contain any command except the following:
ABORT
BYE
CHGROUP
DATA
DISMOUNT
DO
EOD
EOJ
EXIT
HELLO
Note
JOB
LISTREDO
MOUNT
MRJE
NRJE
REDO
RESUME
RJE
SETCATALOG
VSUSER
CIERROR 9103 is returned if
supported.
cmdimage contains a command that is not
For compatibility with MPE V/E, the COMMAND intrinsic converts three error numbers into
CIERROR 975. They are: 9086, 9090, and 9091.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. Although, a CI warning may have been detected.
Request denied. An executor-dependent error, such as an erroneous
parameter, prevented execution of the command. The numeric error code
is contained in cmderror. The command with the error terminated before
executing completely.
Request denied. The command was undened.
Related Information
Intrinsics
Commands
Manuals
HPCICOMMAND
None
Command Interpreter Access and Variables Programmer's Guide
(32650-90011) and MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364)
Command Definitions
4-35
CREATE
NM and CM callable (dierences noted below).
Creates a process as a child of the calling process. Process handling (PH) capability is
required.
Syntax
CA
CA
I16 I16V U16V
CREATE(formaldesig,entryname,pin,parm,loadags,
I16V I16V I16V
U16V
I16V
stacksize,dlsize,maxdata,priorityclass,rank);
Parameters
formaldesig
character array (required)
entryname
The name of the program to be created, specied either in MPE or HFS
syntax. If you are using MPE syntax, formaldesig passes the name, group
(optional), and account (optional) of the le containing the program to be
run, and, if applicable, a lockword. If you are using HFS syntax, formaldesig
passes the relative pathname or the absolute pathname of the le containing
the program to be run. The last element of the array must be a blank. This
parameter is equivalent to the progle parameter of the RUN command.
character array (optional)
Passes the declared entry point (label) in the program where execution is to
begin when the process is activated. The last element of the array must be a
blank. Specify the program's primary entry point with an array consisting
of one blank character. (Equivalent to the entrypoint parameter of the RUN
command.)
pin
Default: The program's primary entry point is used.
16-bit signed integer by reference (required)
parm
Returns the process identication number (PIN) of the newly created process.
This PIN is used by other intrinsics to reference the new process. If an error
is detected, a value of zero is returned.
16-bit signed integer by value (optional)
Passes information to the new process. The new process can access this
information by using the GETINFO intrinsic. (Equivalent to the parm=
parameter of the RUN command.)
Default: parm =0.
4-36
Command Definitions
CREATE
loadags
16-bit unsigned integer by value (optional)
Species the loading options as follows:
Bits
Value/Meaning
15:1
Active:
0 Calling process not activated when the new process
terminates
1 The system reactivates the calling process (parent) when
the new process terminates
14:1
Default: 0
Loadmap (equivalent to the LMAP parameter of the RUN
command):
0 No map produced
1 A list of the allocated (loaded) program is produced on the
job/session list device; displays information about all SOMs
loaded during process creation
13:1
Default: 0
Debug; ignored if nonprivileged and the new process requires
privileged mode or if there is no read/write access for the new
process program le (equivalent to the DEBUG parameter of the
RUN command.):
0 Breakpoint not set
1 Debug called prior to executing the rst instruction of the
new process
12:1
Default: 0
Privilege (equivalent to the NOPRIV parameter of the RUN
command):
0 Program loaded in the mode specied when the program
was linked
1 Program loaded in nonprivileged mode
Default: 0
Command Definitions
4-37
CREATE
Bits
Value/Meaning
10:2
LIBSEARCH bits; species a failed load if the
formaldesignator parameter contains a program name which
cannot be expressed using the MPE syntax. This option is
equivalent to the LIB= parameter of the RUN command:
00 (NM) If formaldesig was linked using the XL= parameter of
the LINK command, then search the libraries specifying XL=
rst. Otherwise, search only the system libraries.
(CM) Search only the system libraries (SL.PUB.SYS).
01 (NM) Search the account public library
(XL.PUB.accountname ) in the account where formaldesig is
located, then search the system libraries.
(CM) Search the account public library
(SL.PUB.accountname ) in the account where formaldesig is
located, then search the system libraries.
10 (NM) Search the group library
(XL.groupname.accountname ) in the account where
formaldesig is located, then the account public library, and
then the system libraries.
(CM) Search the group library
(SL.groupname.accountname ) in the account where
formaldesig is located, then the account public library, and
then the system libraries.
9:1
Default: 00
Control Block; controls where the control blocks of device les
are established and les of type message, RIO, and circular
(equivalent to the NOCB parameter of the RUN command):
0 Establish le control blocks in the process control block
extension (PCBX) area of the CM stack
1 Establish le control blocks in an extra data segment
Default: 0
4-38
Command Definitions
CREATE
Bits
Value/Meaning
7:2
5:2
Reserved for operating system
Stack dump; control the enabling/disabling mechanism where
the stack is dumped in the event of an abort:
00 Stack dump mechanism enabled only at parent level
01 Stack dump mechanism enabled unconditionally
10 Stack dump mechanism enabled only at parent level
11 Stack dump mechanism disabled unconditionally for new
process
4:1
3:1
0:3
stacksize
Default: 00
Reserved for operating system
DL to initial Q; ignored if formaldesig species a native mode
program le. Used for backward-compatibility with MPE
V/E-based systems only.
Reserved for operating system; used only when bits (5:2)=01.
16-bit signed integer by value (optional)
(NM) Ignored if formaldesig species an NM program le (used for
backward-compatibility with MPE V/E-based systems only). The NM stack
is created using NM default values. The CM stack is created using MPE
V/E mode default values. (Equivalent to the stack= parameter of the RUN
command.)
(CM) Passes the number of words assigned to the local stack area bounded by
the initial Q and Z registers. A value of -1 indicates that the Segmenter will
assign the default values (equivalent to omitting this parameter).
Command Definitions
4-39
CREATE
dlsize
16-bit signed integer by value (optional)
(NM) Ignored if formaldesig species an NM program le (used for
backward-compatibility with MPE V/E-based systems only). The NM stack
is created using NM default values and the CM stack is created using MPE
V/E maximum default values. (Equivalent to the DL= parameter of the RUN
command.)
maxdata
(CM) Passes the number of words in the user stack area bounded by the DL
and DB registers. A value of -1 indicates that the Segmenter will assign the
default values (equivalent to omitting this parameter).
16-bit signed integer by value (optional)
(NM) Ignored if formaldesig species a native mode program le (used for
backward-compatibility with MPE V/E-based systems only). The NM stack
is created using NM default values and the CM stack is created using MPE
V/E maximum default values. (Equivalent to the MAXDATA= parameter of the
RUN command.)
(CM) Passes the maximum size allowed for the process stack in words. This
value overrides the value specied at program preparation. A value of -1
indicates that the Segmenter will assign the default value. If not specied in
either the intrinsic call or the program le, the stack size remains the same.
4-40
Command Definitions
CREATE
priorityclass
16-bit unsigned integer by value (optional)
Returns the integer equivalent of two ASCII characters specifying the
priority class where the new process is scheduled (AS, BS, CS, DS, ES). It is
computed as:
(ASCII of first character * 256) +
(ASCII of second character)
The integer equivalents are:
AS
BS
CS
DS
ES
=
=
=
=
=
16,723
16,979
17,235
17,491
17,747
If a user is nonprivileged, the processes can be rescheduled into any of the ve
subqueues except the AS queue. This function is limited by the maximum
priority assigned to the account by the system manager.
If a user is privileged, the processes can be scheduled into any subqueue,
including the AS. A process in the AS or BS linear queue does not give up
CPU voluntarily; it could loop innitely and prevent other processes from
accessing the CPU. (Equivalent to the PRI= parameter of the RUN command.)
rank
Default: The calling process priority.
16-bit signed integer by value (optional)
For backward-compatibility with MPE V/E-based systems only.
Command Definitions
4-41
CREATE
Operation Notes
The CREATE intrinsic does the following:
1. Loads the program to be run by the new process into virtual memory.
2. Creates the process as the child of the calling process.
3. Initializes the process data areas.
4. Schedules the process.
5. Returns the new process identication number (PIN) to the requesting process.
The process is not created and the pin parameter is returned with a value of zero if one of the
following conditions exist:
The value (a nonexistent subqueue) specied is illegal for the priorityclass parameter.
The formaldesig is illegal.
The entryname is illegal.
The program specied by formaldesig contains more capabilities than allowed. PM, MR, or
DS capability is not allowed if the program name uses HFS syntax.
The program specied by formaldesig uses HFS syntax and has PH capability, but the user
does not have PH capability.
A CM program cannot be loaded from the HFS directory.
The process is not created and the pin parameter is returned unmodied if one of the
following conditions exist:
The program le of the creating process does not have process handling (PH) capability.
A required parameter (formaldesig or pin) is omitted.
A reference parameter is not within the required range.
The program name is equal to blank spaces.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The new process has been created.
Request granted.
Request denied. The specied formaldesig or entryname does not exist.
Related Information
Intrinsics
Commands
Manuals
4-42
ACTIVATE, SUSPEND
RUN
Process Management Programmer's Guide (32650-90023)
Command Definitions
CREATEPROCESS
CREATEPROCESS
NM and CM callable (dierences noted below).
Creates a process and allows you to assign $STDIN and $STDLIST to any le. Process handling
(PH) capability is required.
Syntax
I*
I16
CA
CREATEPROCESS(createstatus,pin,formaldesig,
I*A I*A
itemnums,items);
Parameters
createstatus
(NM) 32-bit signed integer by reference (required)
(CM) 16-bit signed integer by reference (required)
Returns a value indicating the type of success or failure. A negative value
indicates that the associated message is a warning, an error terminates the
intrinsic call, and a warning means the call continues. Check the job control
word (JCW) before continuing. The following is a list of the possible values
returned:
Value
0
1
2
3
4
5
6
7
8
-9
-10
Meaning
Successful
Process handling (PH) capability required
Pin or formaldesig parameter missing; or one of itemnum pair
is missing (for example, 11 and 12 or 19 and 24)
Parameter address (other than createstatus ) out of bounds
Out of system resources
Process not created; invalid itemnum specied; or, for a
compatibility mode process, total requested stack space
exceeds maximum congured.
Process not created; formaldesig does not exist
Process not created; formaldesig invalid
Process not created; entry name invalid or does not exist
Process created; LIBSEARCH bits ignored
Process created; itemnum =19 ignored
Command Definitions
4-43
CREATEPROCESS
Value
15
16
17
18
19
20
Meaning
Process not created; reserved item was specied
Process not created; hard load error occurred (for example,
I/O error reading formaldesig )
Process not created; illegal value specied for itemnum =7
Process not created; specied $STDIN could not be opened
Process not created; specied $STDLIST could not be opened
Process not created; string to be passed to new process invalid
(pointer without length, length without pointer, or length
exceeds stack size of calling process)
pin
16-bit signed integer by reference (required)
formaldesig
Returns the process identication number (PIN) of the newly created process.
This PIN is used by other intrinsics to reference the new process. If an error
is detected, a value of zero is returned.
character array (required)
itemnums
Passes the name of the program le to be run. Terminate the string with any
nonalphanumeric character other than a period (.) or a backslash (/). This
paramenter is equivalent to the progle parameter of the RUN command.)
(NM) 32-bit signed integer array (optional)
(CM) 16-bit signed integer array (optional)
Species which item value is to be passed. (Refer to Table 4-1.)
items
Values passed may be passed by value.
(NM) 32-bit signed integer array (optional)
(CM) 16-bit signed integer array (optional)
Species if the formaldesig parameter contains a program name that is
unrecognizable using MPE syntax, LIBSEARCH will result in a failed load.
4-44
Command Definitions
CREATEPROCESS
Table 4-1. CREATEPROCESS Itemnum/Item Values
Itemnum
Item Description
0
Indicates the end of the option list. No value is required in the corresponding item .
1
The address must be a byte address (type-coerced) containing the entry point name in the
program where the new process is to begin execution (equivalent to the entrypoint
parameter of the RUN command.) The name consists of a string of characters terminated by
a blank.
2
A value passed to the new process (equivalent to the PARM= parameter of the RUN command.)
3
The load options for loading the program le of the new process, designated as:
(NM)
Bits (0:16)
Bits (16:16)
Zeros
Load options
(CM)
Bits (0:16)
Load options
Item 3 has the same denition as the loadag parameter of the CREATE intrinsic. If both
itemnum s 3 and 19 are specied, the LIBSEARCH option is ignored or if LIBSEARCH is set to
a value other than its default (00), a warning is returned indicating the LIBSEARCH option
was ignored.
4,5,6
(CM Only) Ignored if formaldesig species an NM program le; created using MPE V/E
maximum default values (equivalent to the STACK=, DL=, and MAXDATA= parameters of the
RUN command).
7
The priority class where the new process is scheduled (AS, BS, CS, DS, ES); is computed as
(equivalent to the PRI= parameter of the RUN command.):
(ASCII of first character * 256) + (ASCII of second character)
The integer equivalents are:
AS = 16,723
BS = 16,979
CS = 17,235
DS = 17,491
ES = 17,747
If in user mode (nonprivileged), any priority class can be specied except AS; this is limited
by the maximum priority assigned to the account by the system manager. If PM capability
has been assigned, processes can be scheduled into all subqueues. A process in the linear
queue AS or BS does not give up the CPU voluntarily, it could loop innitely and prevent
other processes from accessing the CPU.
Default: The calling process priority class.
Command Definitions
4-45
CREATEPROCESS
Table 4-1. CREATEPROCESS Itemnum/Item Values (continued)
Itemnum
Item Description
8
The address must be a byte address (type-coerced) containing a denition of the le to be
used as $STDIN for the new process (equivalent to the STDIN= parameter of the RUN
command). Must contain an ASCII string (terminated by a carriage return) specifying the
le to be used as $STDIN (that is, everything after the FILE formaldesig= ; portion of the le
equation). If itemnum =8 is not specied, the default $STDIN and $STDLIST (current for the
creating (parent) process) are used for the new process creation.
9
The address must be a byte address (type-coerced) containing a denition of the le to be
used as $STDLIST for the new process (equivalent to the STDLIST= parameter of the RUN
command). If itemnum=9 is not specied, the default $STDIN and $STDLIST (current for
the creating (parent) process) are used for the new process creation.
10
Specifying this item is equivalent to calling the ACTIVATE intrinsic with the newly created
process. The value passed is equivalent to the allow parameter of ACTIVATE , except bit
(31:1) is the parent activation bit and bit (30:1) is the child activation bit.
11
The address must be a byte address (type-coerced) containing information to be passed to
the new process. The length of the string must be specied in itemnum =12 (equivalent to
the INFO= parameter of the RUN command), accessible through the GETINFO intrinsic.
12
The length (in bytes) of the string referenced by itemnum =11. The maximum allowable
value of the INFO string length is 1024 bytes. Accessible through the GETINFO intrinsic.
13
Not used.
14
The address must be a byte address (type-coerced) containing a denition of the le to be
used as $STDERR for the new process. If itemnum =14 is not specied, the $STDERR (current
for the creating (parent) process) is used for the new process creation.
Redirecting output to $STDERR permits the user to write errors to a user-specied disc le.
15-18
19
(NM Only) Reserved for the system.
(NM Only) The address (type-coerced) containing a list of unresolved external references
found in formaldesig (equivalent to the XL= parameter of the RUN command). When
formaldesig contains a name in MPE syntax, the le names must follow le naming
conventions and be separated by commas. When formaldesig contains a name in HFS
syntax, you must use an absolute pathname and the le names specied in this item must
be fully qualied.
If itemnum s 3 and 19 are specied, the LIBSEARCH option in itemnum =3 is ignored or if
LIBSEARCH is set to a value other than its default (00), a warning is returned indicating the
LIBSEARCH option was ignored. The length of the string must be specied in itemnum =24.
20-22
23
4-46
(NM Only) Reserved for operating system.
(NM Only) The address (type-coerced) containing the name of a procedure to link
unsatised references to. The name consists of a string of characters terminated by an
ASCII carriage return character or a blank (equivalent to the UNSAT= parameter of the RUN
command).
Command Definitions
CREATEPROCESS
Table 4-1. CREATEPROCESS Itemnum/Item Values (continued)
Itemnum
Item Description
24
(NM Only) The length of the string referenced by itemnum =19.
25
(NM Only) Reserved for operating system.
26
The address must be a byte address containing the maximum size (in bytes) that the NM
stack can grow (equivalent to the NMSTACK= parameter of the RUN command).
27
The address must be a byte address containing the maximum size (in bytes) that the NM
heap can grow (equivalent to the NMHEAP= parameter of the RUN command).
Condition Codes
CCE (2)
CCG (0)
Request granted.
Request granted. Check the createstatus parameter to see if warning codes
were returned. nCCL (1)nRequest denied. Check the createstatus parameter
to determine why the request was denied.
Related Information
Intrinsics
Commands
Manuals
CREATE
RUN
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-47
CTRANSLATE
NM and CM callable.
Converts a string of characters between EBCDIC and ASCII, or between EBCDIK
(HP-specic version of EBCDIC) and KANA8 (8-bit, Japanese International Standard (JIS)
version of USASCII code).
Syntax
I16V
CA
CA
CTRANSLATE( transcode,inbuer,outbuer,
I16V
CA
buerlength,transtable);
Parameters
transcode
16-bit signed integer by value (required)
Passes one of the following translation identiers:
Value
0
1
2
3
4
5
6
Meaning
User-supplied table specied in the transtable parameter
Convert EBCDIC to ASCII
Convert ASCII to EBCDIC
Reserved for operating system
Reserved for operating system
Convert EBCDIK to KANA8 (JIS)
Convert KANA8 (JIS) to EBCDIK
inbuer
character array (required)
outbuer
Passes the string of characters to be translated.
character array (optional)
buerlength
Passes the translated character string. If an outbuer parameter is not
specied, all translation occurs within inbuer. The inbuer and outbuer
parameters can specify the same array.
16-bit signed integer by value (required)
Passes the number of characters to be converted.
4-48
Command Definitions
CTRANSLATE
transtable
character array (required when transcode=0, otherwise optional)
Passes the user-dened translation table. The contents and order of transtable
dene the translation process. Transtable must be <= 256 bytes. Transtable
is constructed so that each byte corresponds to a byte value in the source
string to be translated. For example, the rst byte in transtable gives the code
to be substituted for source bytes whose value is 0.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. Translation performed successfully.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Data Types Conversion Programmer's Guide (32650-90015)
Command Definitions
4-49
CTRANSLATE
DASCII
NM and CM callable.
Converts a 32-bit binary number to a specied base and represents it as a numeric ASCII
string.
Syntax
I16
I32V
I16V
CA
numchar:=DASCII(binvalue,base,asciieqv);
Functional Return
numchar
16-bit signed integer (assigned functional return)
Returns the number of characters in the resulting string.
Parameters
binvalue
32-bit signed integer by value (required)
base
Contains the binary number to be converted to an ASCII string.
16-bit signed integer by value (required)
Contains one of the following translation identiers:
Value
8
10
-10
16
asciieqv
4-50
Meaning
Convert to octal (pad with zeros)
Convert to decimal (left-justied)
Convert to decimal (right-justied)
Convert to hexadecimal (pad with zeros)
If any other number is entered in this parameter, the intrinsic causes the
process to abort.
character array (required)
Returns the converted value. Must be long enough to contain the result (<=
11 characters).
For octal conversions (base=8), 11 characters (including leading zeros)
are returned; numchar returns the number of signicant (right-justied)
characters (excluding leading zeros). If binvalue=0, the length returned is
1.
For decimal conversions (base=10), binvalue is considered a 32-bit twos
complement integer ranging from -2,147,483,648 to +2,147,483,647. If
binvalue=0, only one zero character is returned in asciieqv; numchar
Command Definitions
DASCII
returns the total number of characters (including the sign). For example, if
binvalue=0, the length returned is 1.
For hexadecimal conversions (base=16), 8 characters (including leading
zeros) are returned. The digits can be 0..9 and A..F.Numchar returns
the number of signicant (right-justied) characters (excluding leading
zeros). For example, if binvalue=32, numchar is 2 and asciieqv will be
00000020.
Related Information
Intrinsics
Commands
Manuals
ASCII
None
Data Types Conversion Programmer's Guide (32650-90015)
Command Definitions
4-51
DATELINE
NM and CM callable.
Returns the current date and time, including the day of week, month, day, year, hours, and
minutes.
Syntax
CA
DATELINE(datebuer);
Parameters
datebuer
character array (required)
Returns the date and time information, in a 27-character array, in the format:
FRI, MAY 19, 1989, 12:06 PM
Related Information
Intrinsics
Commands
Manuals
4-52
ALMANAC
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
DBINARY
DBINARY
NM and CM callable.
Converts a numeric ASCII string to a 32-bit binary value. The numeric ASCII string can be
octal, hexadecimal, or decimal.
Syntax
I32
CA
I16V
dbineqv:=DBINARY(dasciieqv,length);
Functional Return
dbineqv
32-bit signed integer (assigned functional return)
Returns the converted 32-bit binary value.
Parameters
dasciieqv
character array (required)
length
Passes the octal or signed decimal number (in ASCII characters) to be
converted. If the character string begins with a percent sign (%), it is treated
as an octal value. If the character string begins with a dollar sign ($), it is
treated as a hexadecimal value. In this case, the string must be less than 6
characters and only 0 through 9, a through f, and A through F are allowed.
If the string begins with a plus sign, minus sign, or a number, it is treated as
a decimal value. Leading blanks are not allowed and are treated as illegal
characters.
16-bit signed integer by value (required)
Returns the length (number of bytes) of the ASCII-coded value:
If the value of length is 0, the intrinsic returns 0 to the calling process.
If the value of length is negative, the intrinsic causes the process to abort.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. A 32-bit binary value is returned to the process.
Request denied. A word overow, possibly resulting from too many characters
(dasciieqv number too large), occurred in the value (dbineqv ) returned.
Request denied. An illegal character was encountered in dasciieqv. For
example, the digits 8 or 9 were specied in an octal value.
Command Definitions
4-53
DBINARY
Related Information
Intrinsics
Commands
Manuals
4-54
BINARY
None
Data Types Conversion Programmer's Guide (32650-90015)
Command Definitions
DEBUG
DEBUG
NM and CM callable.
Invokes the debug facility from an interactive program and allows object code to be analyzed.
Note
Consult the MPE/iX System Debug Reference Manual (32650-90013) before
attempting to use the debug facility.
Syntax
DEBUG;
Operation Notes
The debug facility has its own set of commands and a symbolic window display feature. The
intrinsic call acts as a hard-coded breakpoint. Execution of the calling program is halted and
the debug facility prompt is displayed. If the call is made from a batch program, it is ignored.
Related Information
Intrinsics
Commands
Manuals
None
None
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
4-55
DLSIZE
NM and CM callable.
Causes the area between DL and DB in the compatibility mode (CM) stack to be expanded or
contracted within the CM stack segment.
Syntax
I16
I16V
dldbsize:=DLSIZE(size);
Functional Return
dldbsize
16-bit signed integer (assigned functional return)
Returns the granted number of half words for the DL-to-DB area. This value
is negative, unless error condition CCL (1) is returned; a positive value is
possible.
Parameters
size
16-bit signed integer by value (required)
Passes the desired number of half words for the DL-to-DB area, represented
by a negative value. A size of 0 is permitted and resets the DL-to-DB area
of the CM stack to the original value assigned when the process was created
(initial DL). The size granted is the absolute value of size, rounded up so that
the distance between the beginning of the segment and DB is a multiple of
128 half words.
Operation Notes
If expanding, all information in the area between DL and DB is saved. If contracting, all
information in the area between DL and DB is lost.
If the DL area has been expanded, it can be contracted by calling DLSIZE with a size
parameter requesting a smaller DL-to-DB area.
When called from programs running in NM the DLSIZE intrinsic aects the CM stack only;
programmatic expansion and contraction in NM is not necessary.
Caution
Because of dierences between DB-relative addressing (used in compatibility
mode) and virtual addressing (used in native mode), calls to the DLSIZE
intrinsic in mixed mode programming may cause stack corruption.
Hewlett-Packard does not recommend using the DLSIZE intrinsic in programs
that move between Native mode and compatibility mode.
4-56
Command Definitions
DLSIZE
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The value returned is >= the value requested.
Request denied. The requested size exceeded the maximum limit allowed.
The maximum limit allowable is granted, and its size is returned.
Request denied. An illegal size parameter was specied, the size requested is
less than the initial DL size, or the size parameter was a positive integer.
The original area size, assigned when the CM stack segment was created, is
granted.
Related Information
Intrinsics
Commands
Manuals
None
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
4-57
DMOVIN
NM and CM callable.
Copies data from an extra data segment into a data area. Data segment management (DS)
capability is required.
Data segment management (DS) intrinsics are not recommended for use in the
NM programming environment; use of DS intrinsics in NM degrades an NM
program's performance.
Note
Syntax
U16V
I16V
I16V
U16A
DMOVIN(index,displacement,number,location);
Parameters
index
16-bit unsigned integer by value (required)
displacement
Species the index of the extra data segment, obtained from a GETDSEG
intrinsic call.
16-bit signed integer by value (required)
number
Species the displacement, in half words, of the rst half word in the string to
be transferred from the rst half word in the data segment. This value must
be >=0.
16-bit signed integer by value (required)
location
Species the size, in half words, of the data string to be transferred. This
value must be >=0.
16-bit unsigned integer array (required)
Contains the array (buer) in the stack where the data string is to be moved.
4-58
Command Definitions
DMOVIN
Operation Notes
When DMOVIN is called, a bounds check is initiated to ensure that the data is taken from
within the data segment boundaries and moved to an available data area. For example, in
Figure 4-1, to move four half words from locations 422 through 425 of the extra data segment
(whose index is 21) to array ARA (located in your data area), the intrinsic call would be:
DMOVIN(21,422,4,ARA[10]);
The index is 21 (refer to GETDSEG); displacement within the data segment is 422; the
number of half words to move into the data area is 4; and the location to begin transferring
the data is the address of ARA[10]. If ARA is an array of half words, the four half words are
moved to ARA[10] through ARA[13], as shown in Figure 4-1.
d
c
a
ARA[1..n]
1 +--------------+
2 |--------------|
3 |--------------|
4 |--------------|
5 |--------------|
6 |--------------|
7 |--------------|
8 |--------------|
9 |--------------|
10 |--------------|
11 |--------------|
12 |--------------|
13 |--------------|
14 +--------------+
.
.
.
+--------------+
n +--------------+
Extra
0
1
2
Data Segment
+--------------+
|--------------|
+--------------+
.
.
.
+--------------+
420 |--------------|
421 |--------------|
<-------- 422 |--------------|
<-------- 423 |--------------|
<-------- 424 |--------------|
<-------- 425 +--------------+
.
.
.
+--------------+
12000 +--------------+
b
Figure 4-1. DMOVIN Data Movement.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. A bounds-check failure occurred.
Request denied. Illegal index or number parameter.
Command Definitions
4-59
DMOVIN
Related Information
Intrinsics
Commands
Manuals
4-60
DMOVOUT, GETDSEG
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
DMOVOUT
DMOVOUT
NM and CM callable.
Copies data from the data area to an extra data segment. Data segment management (DS)
capability is required.
Note
Data segment management (DS) intrinsics are not recommended for use in the
NM programming environment; use of DS intrinsics in NM degrades the NM
program's performance.
Syntax
U16V
I16V
I16V
U16A
DMOVOUT(index,displacement,number,location);
Parameters
index
16-bit unsigned integer by value (required)
displacement
Species the index of the extra data segment, obtained from a GETDSEG
intrinsic call.
16-bit signed integer by value (required)
number
Species the displacement, in half words, of the rst half word in the string to
be transferred from the rst half word in the data segment. This value must
be >=0.
16-bit signed integer by value (required)
location
Species the size, in half words, of the data string to be passed. This value
must be >=0.
16-bit unsigned integer array (required)
Passes the data string to be moved to the extra data segment.
Command Definitions
4-61
DMOVOUT
Operation Notes
When DMOVOUT is called, a bounds check is initiated to ensure that the data is taken from
within an available data area and moved to an area within the extra data segment boundaries.
For example, in Figure 4-2, to move four half words from ARA[10] to the data segment whose
index is 2 (from a GETDSEG call), starting at location 201 within the segment, the intrinsic call
could be:
DMOVOUT (2,201,4,ARA[10]);
The index is 2; the displacement within the data segment is 201; the number of half words
to be moved to the data segment is 4; and the starting location of the data is the address of
ARA[10]. If ARA is an array of half words, the four half words, from ARA[10] to ARA[13], are
moved to half word oset 201 through 204 of the data segment, as shown in Figure 4-2.
d
c
a
ARA[1..n]
1 +--------------+
2 |--------------|
3 |--------------|
4 |--------------|
5 |--------------|
6 |--------------|
7 |--------------|
8 |--------------|
9 |--------------|
10 |--------------|
11 |--------------|
12 |--------------|
13 |--------------|
14 +--------------+
+--------------+
.
.
+--------------+
n +--------------+
Extra
0
1
2
------>
------>
------>
------>
Data Segment
+--------------+
|--------------|
+--------------+
.
.
.
199 +--------------+
200 |--------------|
201 |--------------|
202 |--------------|
203 |--------------|
204 +--------------+
+--------------+
.
.
.
+--------------+
209 +--------------+
Figure 4-2. DMOVOUT Data Movement.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-62
Request granted.
Request denied. Out of bounds-check failure.
Request denied. Illegal index or number parameter.
Command Definitions
b
DMOVOUT
Related Information
Intrinsics
Commands
Manuals
DMOVIN
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
4-63
ENDLOG
NM and CM callable.
Posts a record to the logging le marking the end of a logical transaction. When the record is
posted, ENDLOG ushes the user logging memory buer to ensure that the record gets to the
logging le. User logging (LG) or system supervisor (OP) capability is required.
Syntax
I32 U16A
I16
I16
I16
ENDLOG(index,data,length,mode,logstatus);
Parameters
index
32-bit signed integer by reference (required)
data
Passes the access to the user logging system. This is the value returned in the
index parameter of the OPENLOG intrinsic.
16-bit unsigned integer array (required)
length
Passes the information to be logged. A log record contains 128 half words,
where 119 half words are available for writing data. For the most ecient use
of log le space, structure arrays with lengths in multiples of 119 half words.
16-bit signed integer by reference (required)
mode
Passes the length of the data in data. A positive value indicates half words,
while a negative value indicates bytes. If the length is greater than 119 half
words (or 238 bytes), the information in data is divided into two or more
physical log records.
16-bit signed integer by reference (required)
Passes a value indicating whether the logging process should suspend your
process if it cannot complete your request for service immediately. If it is not
possible to log the transaction and mode is set to 1 (nowait), the ENDLOG
intrinsic indicates through logstatus that it could not complete your request.
4-64
Command Definitions
Value
Meaning
0
1
Wait
Nowait
ENDLOG
logstatus
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the
intrinsic call:
Value
0
1
2
4
5
9
12
14
15
Meaning
Successful
Nowait mode requested, and the user logging process is busy
Parameter out of bounds
Incorrect index parameter passed
Incorrect mode parameter passed
Error occurred while writing
System out of disk space; user logging cannot proceed
Invalid access
End-of-le encountered
Operation Notes
Use the data parameter of this intrinsic to post user data to the logging le. This use
of ENDLOG is similar to using the WRITELOG intrinsic, but also denotes the end of a logical
transaction.
Related Information
Intrinsics
Commands
Manuals
WRITELOG, OPENLOG
None
User Logging Programmer's Guide (32650-90027)
Command Definitions
4-65
EXPANDUSLF
NM and CM callable.
Changes length of a USL le by creating a USL le with the increment length longer or
shorter than the USL le specied by uslfnum. The old USL le is copied to the new le
with the same le name; the old USL le is then deleted.
A USL contains CM object code and is meaningful only in the CM program
development process.
Note
Syntax
I16
I16V
I16V
lenum:=EXPANDUSLF(uslfnum,increment);
Functional Return
lenum
16-bit signed integer (optional)
Returns the new le number. If an error occurs (condition code returns
CCL (1)), an error number is returned. The condition code must be tested
immediately upon return from this intrinsic. If an error number is used
instead of a le number in the uslfnum parameter, unpredictable results
occur. Following are the possible error numbers and their meanings:
Value
0
1
7
8
9
10
11
4-66
Command Definitions
Meaning
File specied by uslfnum was empty, an unexpected end-of-le
was encountered when reading the old USL le, or an
unexpected end-of-le was encountered when writing the new
uslfnum
Unexpected I/O error occurred; can occur on the old USL le,
or the new uslfnum where the information is being copied to
Unable to open the new USL le
Unable to close (purge) the old USL le
Unable to close (save) the new USL le
Unable to close $NEWPASS
Unable to open $OLDPASS
EXPANDUSLF
Parameters
uslfnum
16-bit signed integer by value (required)
increment
Passes the le number of the le.
16-bit signed integer by value (required)
Passes the number of records the length of the USL le is to be changed:
If a positive value, the new USL le is longer than the old USL.
If a negative value, the new USL le is shorter than the old USL.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The new le number is returned.
Not returned.
Request denied. An error number was returned to lenum .
Related Information
Intrinsics
Commands
Manuals
ADJUSTUSLF
None
MPE Segmenter Reference Manual (30000-90011)
Command Definitions
4-67
FATHER
NM and CM callable.
Returns the process identication number (PIN) of the parent calling process. Process
handling (PH) capability is required.
Syntax
I16
pin:=FATHER;
Functional Return
pin
16-bit signed integer (assigned functional return)
Returns the process identication number (PIN) of the parent process.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The parent is a user process.
Request granted. The parent is a job or session main process (logon CI).
Request granted. The parent is a system process.
Related Information
Intrinsics
Commands
Manuals
4-68
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
FCHECK
FCHECK
NM and CM callable.
Returns specic details about error conditions that occurred when a le system intrinsic
returns a condition code indicating an I/O error. FCHECK applies to les on any device.
Syntax
I16V
I16
I16
I32
I16
FCHECK(lenum,fserrorcode,translog,blocknum,numrecs);
Parameters
lenum
16-bit signed integer by value (optional)
fserrorcode
Passes the le number of the le for which error information is to be returned.
If lenum is set to zero or if it is not specied, error information is returned
about the last failed FOPEN call.
16-bit signed integer by reference (optional)
translog
Returns a le system error code indicating the type of error that occurred.
Refer to Table 4-2.
16-bit signed integer by reference (optional)
blocknum
Returns the number of half words read or written if an I/O error occurred.
(This value is recorded in the transmission log.)
32-bit signed integer by reference (optional)
numrecs
Returns the physical record count for a nonspoolle or the logical record
count for a spoolle:
For xed-length and undened-length record les, the physical count is the
number of physical records transferred to or from the le since FOPEN.
For variable-length record les, the physical count is the last rewind,
rewind/unload, space forward or backward to tape mark.
16-bit signed integer by reference (optional)
Returns the number of logical records in the bad block (blocking factor).
(ASC only) This parameter is not meaningful for asynchronous devices.
Command Definitions
4-69
FCHECK
Table 4-2. File System Error Codes
Error Code
4-70
Description
0
Successful or end-of-le (EOF)
1
Illegal DB register setting
2
Illegal capability
3
Required parameter missing
4
Disk space allocation disabled on all domain disks
5
DRT number >511
6
Device has no spare blocks available
7
Unformatted or uninitialized media on device
8
Illegal parameter value
9
Invalid le type specied in foption
10
Invalid record size specication
11
Invalid resultant block size
12
Record number out of range
13
Cannot open le multiaccess
16
More than 255 opens of a le
15
Exceeded maximum le opens for write access
17
Magnetic tape runaway
18
Device powered up
19
Forms control was reset
20
Invalid operation requested (for example, terminal type set to -24 which is an invalid
entry)
21
Data parity error
22
Timeout (read timeout value set with FCONTROL itemnum =4)
23
End-of-tape
24
Device not ready; not online, modem dsr signal not \high", or line disconnected)
25
No write ring on tape
26
Transmission error
27
I/O timeout; block mode read timer expired (timer set by system, not user changeable)
28
Timing error; data arrived at controller faster than it could be serviced (data overrun)
Command Definitions
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
Description
29
Start I/O (SIO) failure
30
Unit failure
31
End-of-line (EOL) special character terminator or additional end-of-record (AEOR)
character (dened by FCONTROL itemnum =25)
32
Software abort of I/O operation (for example, an ABORTIO command was entered)
33
Data lost or no buer available
34
Unit not online
35
Data set not ready
36
Invalid disk address
37
Invalid memory address
38
Tape parity error
39
Recovered tape error
40
Operation inconsistent with access type
41
Operation inconsistent with record type
42
Operation inconsistent with device type (for example, attempted to set an invalid line
speed through FCONTROL itemnum =11)
43
Write exceeds record size
44
Update at record zero
45
Privileged le violation
46
Out of disk space
47
I/O error on a le label
48
Invalid operation; multiple le access
49
Unimplemented function
50
Nonexistent account
51
Nonexistent group
52
Nonexistent permanent le
53
Nonexistent temporary le
54
Invalid le reference
Command Definitions
4-71
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
4-72
Description
55
Device unavailable
56
Invalid device specication
57
Out of virtual memory
58
No le passed
59
Standard label violation
60
Global RIN not available or insucient system resources
61
Out of group disk space
62
Out of account disk space
63
No nonshareable device capability
64
Program not prepared with multiple RIN capability
66
Plotter limit switch reached
68
Insucient system resources
69
I/O error
70
I/O error while printing header/trailer, or an FOPEN or FCLOSE failed
71
Too many les open
72
Invalid le number
73
Bounds violation
74
No room in stack for le entry
77
Nowait I/O operation pending
78
No nowait I/O pending for any le
79
No nowait I/O pending for any special le
80
Spoolle size exceeds conguration
81
No spool class dened in system
82
Insucient space in spool class for I/O request
83
I/O error on spoolle
84
Device unavailable for spoolle
85
Operation inconsistent with spooling (for example, attempt to read hardware status)
86
Spooling internal error
87
Bad spoolle block
Command Definitions
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
Description
88
Nonexistent spoolle
89
Power failure
90
Exclusive violation; le being accessed
91
Exclusive violation; le accessed exclusively
92
Lockword violation
93
Security violation
94
User not creator
95
Read not completed; the terminal user pressed 4BREAK5 (The user must enter the
RESUME command to continue. The le system sees the restart, the application does
not.)
96
Disk I/O error
97
No control-Y PIN
98
Read timer overow; read exceeded maximum capacity of read timer (655.35 seconds)
99
BOT and backspace tape
100
Duplicate permanent le name
101
Duplicate temporary le name
102
I/O error on directory
103
Permanent directory overow
104
Temporary directory overow
105
Bad variable block structure
106
Extent size exceeds maximum
107
Insucient space for user labels
108
Invalid le label
109
Invalid carriage control
110
Attempt to save permanent le as temporary
111
No save les (SF) capability
112
No mountable volumes (UV) capability
113
Volume set not mounted; mount problem
114
Volume set not dismounted; dismount problem
115
Attempted rename across volume sets rejected
Command Definitions
4-73
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
4-74
Description
116
Invalid tape label FOPEN/HPFOPEN parameters
117
Attempted write on an unexpired tape le
118
Invalid header or trailer tape label
119
I/O error positioning tape for tape labels
120
Attempted write on an IBM standard tape label
121
Tape label lockword violation
122
Tape label table overow
123
End of tape volume set
124
Attempt to append labeled tape
125
Expiration date later than preceding le
126
Character set number must be between 0 and 31
127
Form number must be between 0 and 31
128
Logical page number must be between 0 and 31
129
Vertical format number must be between 0 and 31
130
Number of copies must be between 1 and 32,767
131
Number of overlays must be between 1 and 8
132
Page length parameter must be between 12 (=3) and 68 (=17)
133
Picture number must be between 0 and 31
134
Extended capability parameter must be 0 (OFF) or 1 (ON)
137
Defective track on foreign disk
138
Track does not exist on foreign disk
139
Deleted record on IBM diskette
148
Inactive RIO record
149
Missing item number or return variable
150
Invalid itemnum
151
Undened le type
152
Unrecognized option in FOPEN/HPFOPEN device parameter
153
Expecting semicolon (;) or carriage return in FOPEN/HPFOPEN device parameter
154
Environment le open error
155
File not environment le; check le code or record size
Command Definitions
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
Description
156
Header record incorrect
157
Uncompiled environment le
158
Error reading environment le
159
Error closing environment le
160
Error doing FDEVICECONTROL from environment le
161
Too many parameters in device string overow
162
Expecting \=" after option in device parameter
163
Incorrect ENV backreference in le equation
164
Device parameter too large or missing carriage return
165
Invalid density specication
166
FFILEINFO failed while accessing remote spoolle
167
Spoolle label error; cannot insert environment le name
168
Item not supported on remote system
170
Record marked deleted; pointer positioned to a record marked for deletion
171
(KSAM) Duplicate key value not allowed
172
(KSAM) Key not found; invalid key value
173
(KSAM) tcount parameter larger than record size
174
(KSAM) Cannot get extra data segment
175
(KSAM) Internal KSAM error
176
(KSAM) Illegal extra data segment
177
(KSAM) Too many extra data segments for this process
178
(KSAM) Not enough virtual memory for extra data segment
179
(KSAM) File must be locked before issuing this intrinsic
180
(KSAM) KSAM le must be rebuilt; KSAM version does not handle a le built by
previous version
181
(KSAM) Invalid key starting position
182
(KSAM) File empty
183
(KSAM) Record does not contain all keys
184
(KSAM) Invalid record number
Command Definitions
4-75
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
4-76
Description
185
(KSAM) Sequence error in primary key
186
(KSAM) Invalid key length
187
(KSAM) Invalid key specication
188
(KSAM) Invalid device specication
189
(KSAM) Invalid record format
190
(KSAM) Invalid key blocking factor value
191
(KSAM) Record does not contain search key for deletion; specied key value points to
record not containing that value
192
(KSAM) System failure occurred while KSAM le was opened
193
(KSAM) $STDIN/$STDLIST cannot be redirected to KSAM les
194
(KSAM) KSAM les not allowed for global AFTs
196
(KSAM) Language not supported
197
(KSAM) native language internal error
198
(KSAM) Invalid version number in KSAM le
201
(DS) Unable to access DSLINE table
204
(DS) Unable to allocate an extra data segment for DS/DSN 3000
205
(DS) Unable to expand the DS/DSN 3000 extra data segment
214
(DS) Requested DS line has not been opened with a DSLINE command
216
(DS) Message rejected by remote computer
217
(DS) Insucient amount of user stack available
221
(DS) Internal DS error; invalid message format
224
File equations for a remote le constitute a loop
227
RFA/RDBA could not nd or create a remote session
239
Communication interface error; trace malfunction
240
(DS) Local communication line not opened by operator
Command Definitions
FCHECK
Table 4-2. File System Error Codes (continued)
Error Code
Description
241
(DS) DS line in use exclusively or by another subsystem
242
(DS) Internal DS software malfunction
243
(DS) Remote computer not responding
246
Communications interface error; remote computer disconnected
249
Communications interface error; unable to enter remote session
255
Communications interface error; connection lost
302
Invalid item number for FDEVICECONTROL
303
Invalid access for item number to FDEVICECONTROL
304
Attempt to change terminal parity in 8-bit mode
305
Invalid format in terminal conguration le
306
Checksum error in terminal conguration le
307
Passed value to FDEVICECONTROL less than minimum
308
Passed value to FDEVICECONTROL greater than maximum
309
Passed value to FDEVICECONTROL is unsupported
310
Count to FDEVICECONTROL insucient for return information
311
Count to FDEVICECONTROL greater than available store information
312
Passed special character has previously dened function
Operation Notes
FCHECK is used to determine the error conditions of the last failed FOPEN intrinsic call (even if
a le number was not returned) by setting the lenum parameter to zero. In this case, only
fserrorcode returns valid information.
Do not use FCHECK to determine error conditions of a last failed HPFOPEN call; error conditions
are returned in the HPFOPEN status parameter.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The le number passed by lenum is invalid, or a bounds
violation occurred while processing this request (fserrorcode =73).
Command Definitions
4-77
FCHECK
Related Information
Intrinsics
Commands
Manuals
4-78
None
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and MPE XL Asynchronous Serial Communications
Programmer's Reference Manual (32022-90012)
Command Definitions
FCLOSE
FCLOSE
NM and CM callable.
Terminates access to a le on any device.
Syntax
I16V
I16V
I16V
FCLOSE(lenum,disposition,securitycode);
Parameters
lenum
16-bit signed integer by value (required)
disposition
Passes the le number of the le to be closed.
16-bit signed integer by value (required)
Passes the disposition of the le, signicant only for les on disk and magnetic
tape; ignored for spooled and hot printers.
(ASC) This parameter is not meaningful for asynchronous devices.
Note
This disposition can be overridden by a corresponding parameter in a FILE
command entered prior to program execution.
The disposition options are:
Bits
13:3
Value/Meaning
Domain disposition:
000 No change. The disposition remains as it was before the
le was opened. If the le is new, it is deleted by FCLOSE;
otherwise, the le is assigned to the domain it belonged
to previously. An unlabeled tape le is rewound and a
labeled tape is rewound and unloaded.
001 Close as a permanent le. If the le is a disk le, it is
saved in the system le domain. A new or old temporary
le on disk has an entry created for it in the system le
directory. If a le of the same name already exists in the
directory, an error code is returned and the le remains
open. If the le is a permanent le on disk, this domain
disposition has no eect. If the le is stored on magnetic
tape, the tape is rewound and unloaded.
Command Definitions
4-79
FCLOSE
Bits
Value/Meaning
13:3
Domain disposition (Continued):
010 Close as a temporary job le (rewound). The le is
retained in your temporary (job/session) le domain and
can be requested by any process within your job/session.
If the le is a disk le, the le name is checked. If a le of
the same name already exists in the temporary le
domain, an error code is returned and the le remains
open. If a le resides on unlabeled magnetic tape, the
tape is rewound. If the le resides on labeled magnetic
tape, the tape is backspaced to the beginning of the
opened le.
011 Close as a temporary job le (not rewound). This option
has the same eect as domain disposition 010, except that
tape les are not rewound. In the case of unlabeled
magnetic tape, if this FCLOSE is the last done on the
device (with no other FOPEN/HPFOPEN calls outstanding),
the tape is rewound and unloaded. If the le resides on a
labeled magnetic tape, the tape is positioned to the
beginning of the next le on the tape.
100 Release the le. The le is deleted from the system.
101 Makes a permanent standard disk le temporary (valid
only for standard disk les with either xed-length,
variable-length, or undened-length record formats). The
le is removed from the permanent le directory and
inserted into the temporary le directory. (PM capability
is required for this option.)
4-80
Command Definitions
FCLOSE
Bits
Value/Meaning
11:2
Disk space disposition (valid only for standard disk les with
either xed-length, undened-length, or variable-length record
formats):
00
Does not return any disk space allocated beyond the
end-of-le marker.
01
Returns any disk space allocated beyond the end-of-le
(EOF) marker to the system. The EOF becomes the le
limit; records cannot be added to the le beyond the
EOF.
10
0:11
Note
Returns any disk space allocated beyond the end-of-le
(EOF) marker to the system. The le limit remains the
same; records can be added to the le beyond EOF, up to
the le limit. The disk space disposition takes eect on
each FCLOSE.
Reserved for the system.
When a le is opened with the FOPEN/HPFOPEN intrinsic, the le count
(maintained by the operating system for each le) is incremented by one;
when a le is closed, the le count is decremented by one. If more than one
FOPEN/HPFOPEN is in eect for a particular le, its domain disposition is saved
but not aected by the FCLOSE call until the le count is decremented to zero;
the saved disposition is the smallest nonzero disposition parameter specied
for all FCLOSE calls issued against the le.
For example, the le XYZ is opened three successive times by a process. The
rst FCLOSE disposition is 1, the second is 2, and third is 3. On the last
FCLOSE, a disposition of 1 will occur.
Command Definitions
4-81
FCLOSE
securitycode
16-bit signed integer by value (required)
Returns the type of security initially applied to the le (signicant for new
permanent les only). The valid options are:
Value
0
1
Meaning
Unrestricted access; can be accessed by any user, unless
prohibited
Private le creator security; can be accessed only by the creator
The securitycode parameter selects the security mask assigned to new
permanent les whether or not the le is within an MPE group.
(ASC) This parameter is not meaningful for asynchronous devices.
Operation Notes
FCLOSE deletes buers and control blocks where the process accessed the le. It also
deallocates the device where the le resides, and it can change the disposition of the
le. If FCLOSE calls are not issued for all les opened by the process, the calls are issued
automatically by the operating system when the process terminates. All magnetic tape les
are left oine after FCLOSE calls, to indicate that the system operator can remove them.
For circular les, deletion of disk space beyond the end of le is not allowed. Such a request is
not an error but no operation is performed. For RIO les, cutback disposition works the same
as for at les: if you have any access to the le other than read and you call FCLOSE with
disp=%10, the le is closed, the space beyond the EOF is returned to the system, the le's
limit is changed to EOF, and no error is returned.
The FCLOSE intrinsic can be used to maintain position when creating or reading a labeled tape
le that is part of a volume set:
If the le is closed with a disposition code of 3, the tape does not rewind but remains
positioned at the next le.
If the le is closed with a disposition code of 2, the tape rewinds to the beginning of the
le, but is not unloaded.
A subsequent request to open the le does not reposition if the sequence (seq ) subparameter
of formmsg in FOPEN/HPFOPEN species NEXT or the default (1).
A disposition code of 1 (rewind and unload) implies the close of an entire volume set.
If unlabeled magnetic tape is closed with a disposition code of 0, 1, or 4, and the tape was
written to while open, FCLOSE writes three EOFs at the end of the tape before performing a
rewind or rewind/unload. This ensures that all tapes have an acceptable number of EOF
marks at the end. The three EOFs are written only after the last FCLOSE occurs, before the
rewind, and only if the tape was written on.
For circular les, deletion of disk space beyond the end-of-le is not allowed.
If the new le status time stamp has changed, FCLOSE updates this time stamp in the le
label on disk.
(ASC) For serial devices:
4-82
Command Definitions
FCLOSE
If one of the following device settings is altered programmatically, the device returns to the
system default at FCLOSE:
Disable read timeout (value set by FCONTROL itemnum =4).
Disable subsystem break (enabled through FCONTROL itemnum =17).
Enable printing a string of three exclamation points (!!!) when a line is deleted (disabled
through FCONTROL itemnum =35).
Disable transparent editing (enabled through FCONTROL itemnum =41).
These are only the control actions taken by the device control software; additional changes
can result from actions taken by other software modules. For example, if your program
disables the system break feature, break is reenabled on FCLOSE by the CI software.
For most device settings that can be programmatically altered, ensure that the altered
characteristics are returned to their original settings when the program ends unless the
altered setting dene the way the device should act. For example, if the speed setting of a
device is programmatically altered, you should return the terminal to its original setting
unless the new speed setting should remain in eect for other les opened against the
device.
When all les have been closed on a device and the device is no longer under the control of
a program or session, all device characteristics are returned to those specied by the device's
conguration.
Directories exist only in the permanent le domain. Permanent (001) and no change are
the only values supported for disposition (13:3) bits when filenum references a directory.
Attempts to move a directory from the permanent le domain to either the new or temporary
le domain will fail with a CCL condition code and the directory remains open. Directories
cannot be deleted by FCLOSE. Attempts to release a directory will fail with a CCL condition
and the directory remains open.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The le was not closed; an incorrect lenum was specied
or another le with the same name and disposition exists. Any outstanding
write I/Os that failed (for example, buered writes that are done in
background) or an illegal disposition.
Related Information
Intrinsics
Commands
Manuals
FOPEN
None
Accessing Files Programmer's Guide (32650-90017) and MPE XL
Asynchronous Serial Communications Programmer's Reference Manual
(32022-90012)
Command Definitions
4-83
FCONTROL
NM and CM callable.
Performs various control operations on a le or on the device where the le resides, including:
Supplying a printer or terminal carriage control directive.
Verifying I/O.
Reading the hardware status word for the device where the le resides.
Setting a terminal's timeout interval.
Repositioning a le at its beginning.
Writing an end-of-le marker.
Skipping forward or backward to a tape mark.
Syntax
I16V
I16V
*
FCONTROL(lenum,itemnum,item);
Parameters
lenum
16-bit signed integer by value (required)
itemnum
Passes the le number of the le for which the control operation is to be
performed.
16-bit signed integer by value (required)
item
Species which operation is to be performed (refer to Table 4-3).
type varies (required)
Passes/returns a value associated with a control operation as indicated by the
corresponding itemnum parameter (refer to Table 4-3).
(KSAM) This parameter is ignored, but must be specied to satisfy internal
requirements.
4-84
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values
Itemnum Mnemonic
0
U16
Item Description
General device control:
The value specied is passed to the appropriate device driver. A value from the
driver is returned in item. Not valid for spooled device les.
1
U16
Carriage control (CCTL):
Passes a carriage control directive to the driver of the specied nonspooled device
le, regardless of whether the le is opened CCTL or NOCCTL. For spooled
devices, use FWRITE to pass carriage control directives. (Refer to the FWRITE
intrinsic for these directives.)
If item passes either the prespacing (%101 or %401) or postspacing (%100 or
%400) carriage control directives, one of the following values is returned in item ,
indicating the setting of the device prior to the FCONTROL call:
0
Postspacing
1
Prespacing
If both a mode control directive and a carriage control directive need to be
specied, an additional call to FWRITE or FCONTROL must be made.
This itemnum is ignored for byte stream les. It is not applicable to directories
since applications are not permitted to write to directory les.
Default: postspacing with automatic page eject (except for FORTRAN77/XL
and COBOLII/XL: prespacing with automatic page eject).
2
I16
Complete I/O:
Ensures that requested I/O has been physically completed. Valid only for
buered les. Posts the block being written (full or not). Ignored for message
les.
Item is ignored.
This itemnum is supported for byte stream les. It is not applicable to
directories since applications are not permitted to write to directory les.
(KSAM) A checkpoint record is written. In the event of a system crash, recovery
would be done to this state of the les.
3
U16
Device status:
Returns a record containing information about the state of the device associated
with the le immediately after the last I/O operation (including HPFOPEN/FOPEN )
on the le. The record size and contents are device-dependent.
Command Definitions
4-85
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
4
U16
Item Description
Set read timeout interval:
Passes the timeout interval, in seconds, to be applied to the next read from the
specied le. The maximum value allowed is 65,535 seconds. If input is requested
from a le but is not received in this interval, the FREAD request terminates with
CCL (1). The interval is specied in seconds and returned no value. If this
interval is zero, any previously established interval is cancelled, and no timeout
occurs.
If a timeout value is being set for a read posted against a device connected
through a PAD, add enough time to compensate for time delays that may be
caused by the network.
A timeout value should be used for programs reading from an unattended device
to prevent \hangs". Timeouts can be used to terminate binary reads (only as a
safeguard to prevent a program from waiting forever for a read to complete).
Only valid for terminal and message les. Only aects the next read if the le is
being read from the terminal; it must be reissued for each read. If this code is
applied to a message le, item species the length of time that a process waits
when reading from an empty le or writing to a full one and the timeout remains
enabled until it is explicitly cancelled.
During block mode reads, the timer halts when a DC2 character is received. At
this time, the block mode read timer is activated by the system; its values are not
user changeable.
5
U16
Reposition le at its beginning:
The next record, read or written, is the rst record in the le. Not valid for les
accessed as append-only. On a labeled magnetic tape le or serial disk le, the
tape is positioned at the beginning of the opened le, and not necessarily at the
beginning of the volume. Rejected for spooled DATA tapes.
Item is ignored.
This itemnum is supported for byte stream les and all types of directories.
(KSAM) The le is repositioned to the rst logical record; the record with the
lowest value in the current key.
4-86
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
6
U16
Item Description
Write end-of-le:
Marks the end-of-le (EOF) on disk or magnetic tape and is eective only for
those devices:
If used for a disk le it writes a logical end-of-data marker where the le was
last accessed. The disk le label is updated and written to disk.
If used for a le residing on unlabeled magnetic tape, a tape mark is written at
that current position.
If used for message les, it veries the state of the le by writing the le label
and buer area to disk; ensures the message le can survive system crashes. No
EOF is written.
If used for KSAM les, it performs the function of itemnum =2 and writes the
le label. This guarantees that the end-of-le is correct and the extent bit map
is updated.
Rejected for spooled DATA tapes and labeled magnetic tape les.
Item is ignored.
This itemnum is supported for byte stream les. It is not applicable to
directories since applications are not permitted to write to directory les.
7
U16
Space forward to tape mark:
Moves a magnetic tape forward until a tape mark is encountered. If used on
labeled magnetic tapes, the tape is positioned at the beginning of user trailer
labels, if any. Rejected for spooled DATA tapes.
Item is ignored.
(KSAM) Not used for KSAM XL les. For KSAM/3000 les, it clears the key
and data buers of all information and reads the rst 2 sectors of the key le
from disk to buer.
8
U16
Space backward to tape mark:
On unlabeled tapes, moves a magnetic tape backward until a tape mark is
encountered. If used on labeled tapes, the tape is positioned at the beginning of
user header labels, if any. Rejected for spooled DATA tapes.
Item is ignored.
(KSAM) Not used for KSAM les.
9
U16
Rewind and unload tape:
Repositions a magnetic tape le at its beginning and places the tape oine. Not
allowed for labeled tapes. Rejected for spooled DATA tapes and labeled magnetic
tape les.
Item is ignored.
Command Definitions
4-87
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
10
U16
Item Description
Change line speed of a device:
Passes a value specifying a new line speed for both input and output.
The value passed must be expressed in characters per second (1 character per
second = 10-bits per second). The supported choices are:
30
120
240
960
1920
(300 bps)
(1200 bps)
(2400 bps)
(9600 bps)
(19200 bps)
Any setting other than those listed returns CCL (1).
The speed associated with the device must match the physical speed settings of
the device/modem. If the speed setting is changed programmatically, a request
that the speed setting of the device be manually changed should be made.
If issued against a terminal connected through PAD, CCE (2) is returned, but
there is no eect on the transmission speed, and a meaningless value is returned
in item .
When a device is initially opened programmatically, the speed is set to the
default device speed. If the device is opened as a logon device (congured with
speed and parity sensing enabled), the speed setting is sensed from the rst
carriage return character received. The default device speed is congured
through the Node Management Conguration Manager (NMMGR) or the
OpenView DTC Manager (networks managed by an OpenView workstation).
Recongure the device to permanently change the speed.
Not reset in break mode; not reset after FCLOSE.
Item is ignored.
4-88
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
11
U16
Item Description
Change line speed of a device:
Passes a value specifying a new line speed for both input and output.
The value passed must be expressed in characters per second (1 character per
second = 10-bits per second). The supported choices are:
30
120
240
960
1920
(300 bps)
(1200 bps)
(2400 bps)
(9600 bps)
(19200 bps)
Any setting other than those listed returns CCL (1).
The speed associated with the device must match the physical speed settings of
the device/modem. If the speed setting is changed programmatically, a request
that the speed setting of the device be manually changed should be made.
If issued against a terminal connected through PAD, CCE (2) is returned, but
there is no eect on the transmission speed, and a meaningless value is returned
in item .
When a device is initially opened programmatically, the speed is set to the
default device speed. If the device is opened as a logon device (congured with
speed and parity sensing enabled), the speed setting is sensed from the rst
carriage return character received. The default device speed is congured
through the Node Management Conguration Manager (NMMGR) or the
OpenView DTC Manager (networks managed by an OpenView workstation).
Recongure the device to permanently change the speed.
Not reset in break mode; not reset after FCLOSE.
Item is ignored.
Command Definitions
4-89
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
12
U16
Item Description
Enable echo facility:
Returns a value indicating the previous echo status:
0
1
Echo ON
Echo OFF
When enabled, all characters transmitted to the DTC are echoed onto the
terminal's screen (DTC echo). When the system is initialized, all characters are
echoed except for XON, XOFF, NULL, DEL, and DC2. During binary reads, all
characters are passed as data and echoed. For this reason, echo should be
disabled while in binary mode.
During block mode processing, echo should be disabled and local echo should be
used to cause the terminal to write data back to the screen. If VPLUS is being
used for block mode applications, this is done automatically. For all other types
of block mode, disable echo before the block mode read begins.
Echo should be disabled if a terminal user is entering data that should not
appear on the screen (for example, passwords or lockwords).
Echo should be disabled when connecting some nonsupported devices to an
asynchronous port.
Reset in break mode; not reset after FCLOSE. (Default)
13
U16
Disable echo facility:
Returns a value indicating the previous echo status:
0
1
Echo ON
Echo OFF
When enabled, all characters transmitted to the DTC are echoed onto the
terminal's screen (DTC echo). When the system is initialized, all characters are
echoed except for XON, XOFF, NULL, DEL, and DC2. During binary reads, all
characters are passed as data and echoed. For this reason, echo should be
disabled while in binary mode.
During block mode processing, echo should be disabled and local echo should be
used to cause the terminal to write data back to the screen. If VPLUS is being
used for block mode applications, this is done automatically. For all other types
of block mode, disable echo before the block mode read begins.
Echo should be disabled if a terminal user is entering data that should not
appear on the screen (for example, passwords or lockwords).
Echo should be disabled when connecting some nonsupported devices to an
asynchronous port.
Reset in break mode; not reset after FCLOSE.
4-90
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
14
U16
Item Description
Disable system break function:
Enter a value of 1 to disable the system break function.
System break is enabled by default for any terminal on which a session is active.
If a user presses 4BREAK5 or a process calls the CAUSEBREAK intrinsic, the system
attempts to interrupt the processing and place the terminal at the command
interpreter level. Many system commands and program commands (that invoke
subsystems or run user programs) are breakable.
When the system break is enabled and received, EOR, read timer, terminal mode,
and echo values are saved by the DTS software. This allows restoration when
normal processing is resumed. If a system break is entered during processing of a
character mode read or write, data is lost. Any read that is interrupted by a
break is reissued by the system after a RESUME command is entered.
Some application programs change the settings of terminals and/or the
characteristics of their device les. In these cases, it may be undesirable to allow
system break processing to occur. For example, disable system break when using
block mode. This prevents data loss or corruption that could occur if 4BREAK5 is
pressed during a block mode read.
Reset after FCLOSE. If 4BREAK5 is pressed while system break is disabled, no
action is taken by any level of software. System break has no eect on a device
with no active session.
15
U16
Enable system break function:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
System break is enabled by default for any terminal on which a session is active.
If a user presses 4BREAK5 or the CAUSEBREAK intrinsic is called, the system
attempts to interrupt the processing and place the terminal at the command
interpreter level. Many system commands and program commands (that invoke
subsystems or run user programs) are breakable.
When the system break is enabled and received, EOR, read timer, terminal mode,
and echo values are saved by the DTS software. This allows restoration when
normal processing is resumed. If a system break is entered during processing of a
character mode read or write, data is lost. Any read that is interrupted by a
break is reissued by the system after a RESUME command is entered.
Some application programs change the settings of terminals and/or the
characteristics of their device les. In these cases, it may be undesirable to allow
system break processing to occur. For example, disable system break when using
block mode. This prevents data loss or corruption that could occur if 4BREAK5 is
pressed during a block mode read.
Reset after FCLOSE. (Default) If 4BREAK5 is pressed while system break is
disabled, no action is taken by any level of software. System break has no eect
on a device with no active session.
Command Definitions
4-91
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
16
U16
Item Description
Disable subsystem break function:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
Subsystem break is initially disabled on all devices; it must be enabled before it
can be used. It is available only for devices running sessions and has no eect on
programmatically controlled devices. Subsystem break is reset to disabled at
FCLOSE.
When enabled, the user can stop a program-local or subsystem-local command.
It is invoked by the subsystem break character. (The default subsystem break
character is 4CTRL54Y5.)
When enabled for a terminal connected through PAD, the subsystem break must
be followed by 4RETURN5 to signal the PAD that data is ready.
Before enabling the subsystem break, call the XCONTRAP intrinsic to arm the
subsystem break trap procedure. When a subsystem break is entered, the
subsystem break trap is disarmed. The RESETCONTROL intrinsic must be called to
allow another subsystem break to occur.
Subsystem break processing is summarized as follows:
1. A user-written procedure must be provided dening how the subsystem break
trap handler will react upon receipt of a subsystem break. The user program
must contain:
The user written procedure.
A call to XCONTRAP, specifying the external label of the procedure; this arms
the subsystem break trap.
A call to FCONTROL itemnum =17, enabling the subsystem break function.
A call to RESETCONTROL when the program is ready to receive another
subsystem break.
2. A new subsystem break character can be dened through FCONTROL
itemnum =41 if the terminal is placed in transparent mode or through
FDEVICECONTROL, which allows a subsystem break character to be dened
without placing the device in the transparent mode.
3. At any time, FCONTROL can be called to disable the subsystem break.
Reset in break mode; reset after FCLOSE. (Default)
4-92
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
17
U16
Item Description
Enable subsystem break function:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
Subsystem break is initially disabled on all devices; it must be enabled before it
can be used. It is available only for devices running sessions, and has no eect on
programmatically controlled devices. Subsystem break is reset to disabled at
FCLOSE.
When enabled, the user can stop a program-local or subsystem-local command.
It is invoked by the subsystem break character. (The default subsystem break
character is 4CTRL5Y.)
When enabled for a terminal connected through PAD, the subsystem break must
be followed by 4RETURN5 to signal the PAD that data is ready.
Before enabling the subsystem break, call the XCONTRAP intrinsic to arm the
subsystem break trap procedure. When a subsystem break is entered, the
subsystem break trap is disarmed. The RESETCONTROL intrinsic must be called to
allow another subsystem break to occur.
Subsystem break processing is summarized as follows:
1. A user-written procedure must be provided dening how the subsystem break
trap handler will react upon receipt of a subsystem break. The user program
must contain:
The user written procedure.
A call to XCONTRAP, specifying the external label of the procedure; this arms
the subsystem break trap.
A call to FCONTROL itemnum =17, enabling the subsystem break function.
A call to RESETCONTROL when the program is ready to receive another
subsystem break.
2. A new subsystem break character can be dened through FCONTROL
itemnum =41 if the terminal is placed in transparent mode or through
FDEVICECONTROL, which allows a subsystem break character to be dened
without placing the device in the transparent mode.
3. At any time, FCONTROL can be called to disable the subsystem break.
Reset in break mode; reset after FCLOSE. (Default)
Command Definitions
4-93
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
18
U16
Item Description
Disable tape option
(Default)
Item is ignored.
19
U16
Enable tape option:
Item is ignored.
20
U16
Disable the terminal input timer:
Reset in break mode; reset after FCLOSE. (Default)
Item is ignored.
21
U16
Enable the terminal input timer:
Reset in break mode; reset after FCLOSE.
Item is ignored.
22
U16
Read the terminal input timer:
Item returns the measured time duration of the last read.
The result of the read duration timer is returned in hundredths of a second, up to
655.35 seconds.
The operating system times each and every read, therefore, this call should
immediately follow the read of interest with no subsequent reads between.
23
U16
Disable parity checking and generation:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
If a call is issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not take place.
Parity can be used for terminals opened programmatically and for those in session
mode. The default for these is to operate in 8-bit pass-through mode (no parity).
If a terminal detects a parity error, it displays the PAD character.
If a parity error is detected by ASC software, the current read is completed in
error, and no read data is returned. The ASC software reports the error to the
program reading the data.
4-94
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
24
U16
Item Description
Enable parity checking and generation
Item has no meaning; enter a value of 0 to satisfy internal requirements.
If a call is issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not take place.
Parity can be used for terminals opened programmatically and for those in
session mode. The default for these is to operate in 8-bit pass-through mode.
If a terminal detects a parity error, it displays the PAD character.
If a parity error is detected by ASC software, the current read is completed in
error, and no read data is returned. The ASC software reports the error to the
program reading the data.
When enabled, the ASC software generates parity on outgoing data and checks
the parity errors on incoming data. After the parity is checked, the parity bit is
always set to zero. (The program using the data does not need parity data.)
Parity checking is handled the same in block mode and in character mode.
When enabling parity, ensure that the program also requests the terminal
operator to change the physical parity setting of the terminal to the new setting
of the ASC software. Also, if the terminal is to check parity on incoming data,
the local terminal control (used to turn parity checking on or o) should be set
to ON.
Command Definitions
4-95
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
25
U16
Item Description
Dene additional end-of-record characters:
Item passes the value of a character to be used as an additional end-of-record
(AEOR) character. The octal or decimal code for the character must be in the
right byte of the parameter; the left byte is ignored. If the NULL character (%0)
is specied, default EOR conditions are restored.
Normally, character mode reads using standard editing are terminated by a
4RETURN5. The system echoes the carriage return and sends a linefeed to the
terminal, the cursor is positioned at the beginning of the next line, ready for the
next read. If an AEOR is assigned, an EOR character still terminates a read as
usual.
When a read is terminated by an AEOR, the AEOR character is included in
both the data and byte counts. No carriage return or line feed is sent to the
terminal. The read terminates with an error condition indicating that the AEOR
character was encountered.
The AEOR character is also recognized in transparent editing mode, along with a
user-dened EOR character. (This replaces the normal EOR character.)
To disable the AEOR character, indicate item =0.
The following are not recognized as AEOR characters:
ASCII
Characters
Octal Hex Terminal
Code Code Keys
NUL (null)
%0 $0 4CTRL5@
DC1 (XON)
%21 $11 4CTRL54Q5
DC3 (XOFF)
%23 $13 4CTRL54S5
DEL (Rubout) %31 $19 4DEL5
Subsystem Break %177 $77F 4CTRL54Y5 (default)
Note: Avoid using characters that have a special meaning specically, carriage
return, linefeed, cancel, backspace, DC2, or escape. These characters will be
recognized and processed, but they can result in unpredictable and unsuccessful
results.
Do not use 4CTRL54A5 as an AEOR character at the console.
4-96
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
26
U16
Item Description
Disable binary mode:
Item has no meaning, enter a value of 0 to satisfy internal requirements.
Ignored for terminals connected through PAD.
Binary mode is disabled by default.
27
U16
Enable binary mode:
Item has no meaning, enter a value of 0 to satisfy internal requirements.
If this call is issued to a device connected through PAD, it is ignored; however,
the next FREAD posted to the device returns an error.
When binary mode is enabled, no special characters are processed; all characters
are considered data and are passed through without any terminal control actions
being taken. After a binary read, no carriage return or line feed is sent to the
terminal. All carriage control directives are ignored on writes. Unless echo is
disabled, any ASCII DC3 (XOFF) character passed in data is echoed to the
terminal, and the terminal is suspended. Block mode transfers cannot be made.
Binary mode does not take eect until a read is posted to the device following
the FCONTROL call. If binary mode is enabled for both reads and writes, post a 0
byte read immediately after the call to ensure binary mode is enabled.
Binary mode is useful for transferring 8-bit data to and from a terminal. Because
all 8-bits are considered to be data, binary mode is not compatible with parity
checking; parity must be disabled.
In session mode, a system break restores standard editing at the terminal. If
RESUME is entered following the system break, binary mode is restored when the
rst read is posted.
Binary reads are terminated on byte count, as specied in the FREAD, READ, or
READX call. Errors and read timeouts also terminate binary reads, but an error
code is returned and no data is transferred.
Command Definitions
4-97
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
28
U16
Item Description
Disable user block mode:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
Ignored for terminals connected through PAD.
User block mode is not supported with terminal type 18.
Under system default conditions, block mode processing occurs through a
method called Hewlett-Packard block mode. The system controls the block mode
handshake if block mode transfers are being made and the program does not
need to worry about the data transfer protocol. The host transmits a DC1
character to inform the terminal that the system is ready to receive data. The
terminal responds with a DC2 character to inform the system that the next data
transfer is a block mode transmission. The terminal then waits for the host to
send a second DC1 character to initiate the read.
When transmitting data in block mode, the terminal must be congured to be
compatible with the system and the application requesting the block mode
transfer.
Note: Data overruns can occur during block mode transfers. The program must
check for successful completion of each read, and retry as required. Use of timers
during block mode is encouraged to eliminate port \hangs" due to a data overrun
occurring when the last character is read. The standard block mode read timer is
disabled when the user block mode protocol is enabled.
Not reset in break mode; not reset after FCLOSE. (Default)
29
U16
Enable user block mode:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
Ignored for terminals connected through PAD.
User block mode is not supported with terminal type 18.
When user block mode is enabled and block mode transfers are being made, the
program can intervene in the block mode handshake. A user block mode
transaction begins with the DC1 character and then the program takes control of
the handshake until the DC2 character is encountered. The program can perform
additional terminal control functions, such as positioning the terminal cursor,
performing status requests, or collating additional space for buers before
continuing with the data transfer. When the program is ready to receive block
mode data, an additional read must be issued (DC1 character) to complete the
handshake.
When transmitting data in block mode, the terminal must be congured to be
compatible with the system and the application requesting the block mode
transfer.
Note: Data overruns can occur during block mode transfers. The program must
check for successful completion of each read, and retry as required. Use of timers
during block mode is encouraged to eliminate port \hangs" due to a data overrun
occurring when the last character is read. The standard block mode read timer is
disabled when the user block mode protocol is enabled.
Not reset in break mode; not reset after FCLOSE. Under default conditions, user
block mode is disabled.
4-98
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
34
U16
Item Description
Enable line deletion response:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
In character mode, with standard editing, the computer will output !!!, carriage
return, and line feed when the line deletion (cancel) character is entered. This is
referred to as 4CTRL5X echo (the default line deletion character).
Not reset in break mode; reset after FCLOSE. (Default)
For devices connected through PAD the line deletion response is never printed in
response to the line deletion character. If this call is issued, condition code CCE
(2) is returned, but no device control action occurs.
35
U16
Disable line deletion response:
Item has no meaning; enter a value of 0 to satisfy internal requirements.
The line deletion response can be suppressed by calling this parameter. The data
is deleted in the input buer, but no !!!, carriage return, line feed is issued.
Not reset in break mode; reset after FCLOSE (enables line deletion suppression,
the system default condition).
For devices connected through PAD, the line deletion response is never printed in
response to the line deletion character. If this call is issued, condition code CCE
(2) is returned, but no device control action occurs.
36
U16
Set parity:
Item passes a value representing the specied parity condition and then returns
the value of a previous setting:
0 No parity check on input, eighth bit set to 0 on output (parity type = zeros)
1 No parity check on input, eighth bit set to 1 on output (parity type = ones)
2 Even parity checked on input, even parity generated on output (parity type =
even)
3 Odd parity checked on input, odd parity generated on output (parity type =
odd)
When specied, this option changes the terminal parity setting, and the previous
setting is returned to the call as the new value of item . It is possible to determine
a terminal's parity setting with parity disabled.
Parity cannot be used with 8-bit character sets.
Ignored for devices connected through PAD.
Command Definitions
4-99
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
37
U16
Item Description
Set terminal type and speed:
Item passes a value specifying line speed and terminal type. Bits (0:11) specify
the line speed; bits (11:5) specify the terminal type.
Ensure that the speed associated with a device matches the physical speed
setting of the device and modem (if part of the connection). If the device speed is
being changed programmatically, request that the speed setting be manually
changed on the device.
If an attempt is made to set an unsupported speed or terminal type, condition
code CCL (1) is returned.
Do not use this call to specify a user-dened terminal type.
If used for devices connected through PAD, the call changes the terminal type
setting, but does not change how the device actually operates. Condition code
CCE (2) is returned.
38
U16
Set terminal type
Item passes the value of the system-dened terminal type to be associated with
an asynchronous port.
Changes the terminal type associated with a port to another system-dened
terminal type. The new terminal type remains in eect until another FCONTROL
call is made or the device is closed. If the device is closed, the port resets to its
congured terminal type.
The terminal type specied must be a currently supported system-dened
terminal type. If another value is used, condition code CCL (1) is returned.
This call cannot be used to change to a user-dened terminal type.
If used for a terminal connected through PAD, there is no eect on the terminal
control settings of the device. Condition code CCE (2) is returned.
39
U16
Obtain terminal type information
Item returns the terminal type associated with the asynchronous port. Use this
information to get the original setting before calling itemnum =37 or 38.
Note: Do not confuse the current terminal type returned with the default
terminal type specied during system conguration. Changing the terminal type
during logon or through system intrinsics can cause a dierence from the
congured setting. To reset the congured terminal type, use itemnum =37 and
item =0 or close the device.
4-100
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
40
U16
Item Description
Obtain terminal output speed
Item returns the current line speed associated with an asynchronous port in
characters per second. Use this information to get the original setting before
calling itemnum =11 or 37.
Note: Do not confuse the current line speed returned with the default line speed
specied during system conguration. Changing the line speed through system
intrinsics can cause a dierence from the congured setting. To reset the
congured line speed, use itemnum =37 and item =0 or close the device.
If used for a terminal connected through PAD, the value returned in item is
meaningless. Condition code CCE (2) is returned.
41
U16
Enable transparent editing:
Item passes a value to be used as a subsystem break character in bits (0:8) and a
value to be used as a read terminator in bits (8:8). Returns the values previously
assigned for use as subsystem break and read terminator characters.
When enabled, allows most special characters to be read and treated as data and
a small subset to retain their meaning:
AEOR
The AEOR character dened through a previous call to
itemnum =25. The read terminates in error, and a call to
FCHECK returns an error code of 31. The AEOR character is
passed with the data and included in the byte count.
4BREAK5
Causes a system break (when enabled) and transfers control to
the operating system. If the RESUME command is entered,
transparent editing is resumed.
4CTRL5Q
or XON)
(DC1
The resume output character of the XON/XOFF handshake.
This character is stripped from the input data when
XON/XOFF protocol is enabled.
DC2
When input as the rst character, it is stripped out. A DC1
(4CTRL5Q) is written to the terminal. If not input as the rst
character, DC2 is a data character.
4CTRL5S
(DC3
or XOFF)
The stop output character of the XON/XOFF handshake. This
character is stripped from the input data when XON/XOFF
protocol is enabled.
item bits (0:8)
Species the character that replaces the subsystem break
character. Any character not dened as a special character in
transparent mode (including the standard subsystem break
character) can be used. If set to 0, subsystem break is disabled.
item bits (8:8)
Species the character that replaces the line termination
character (EOR). Any character not dened as a special
character in transparent mode can be used.
Item =0 disables transparent editing mode and returns to standard editing mode.
Command Definitions
4-101
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
Transparent mode reads can be terminated in any of the following ways:
41
Cont'd
The read encountered the EOR character dened in item . This character
functions like a 4RETURN5 character in normal reads and is stripped when
found. No carriage return or line feed is sent to the terminal.
The read encountered an AEOR character, dened through a previous call to
FCONTROL itemnum =25. The read completes with an error condition and the
AEOR character is passed with the input data and and included in the byte
count. No carriage return or line feed is sent to the terminal.
The expected byte count is reached. The read is terminated normally, and
carriage return and line feed are sent to the terminal.
The read limit timer expired. All data is lost and the read terminates in error.
Break or subsystem break processing, if not disabled, occurs in transparent
editing. During a break, the terminal operates in standard editing mode. The
terminal returns to transparent editing mode if the RESUME command is entered.
During a subsystem break, the terminal operates the way the application
program describes.
Parity processing is the same in transparent editing as it is in standard editing.
Any FCLOSE call issued against the terminal restores standard editing.
If used for a device connected through PAD, data is not forwarded from the
terminal immediately after the characters dened as the subsystem break or
EOR character are typed. The terminal user has to press 4RETURN5 to cause data
to be transmitted, or wait for the data forwarding timer to expire (if set). The
host software recognizes and acts on the characters dened in item .
43
U16
Aborts pending nowait I/O request:
For message les, CCG (0) is returned when an outstanding I/O operation has
completed. An IOWAIT call must be issued to nish the request.
45
U16
Enable/disable extended wait:
Applicable only if lenum species a message le. An item value of 1 enables
extended wait; permits a reader to wait on an empty le that is not currently
opened by any writer, or a writer to wait on a full le that has no reader. This
remains in eect until an FCONTROL call is issued with an itemnum 45 and an
item value of 0. An item value of 0 species that if a second FREAD call is issued
and it encounters an empty le that has no reader, it returns an end-of-le
condition. Each assessor must call FCONTROL45 individually.
Default: 0
4-102
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
46
U16
Item Description
Enable/disable reading writer's ID:
Applicable only if lenum species a message le.
For interprocess communication, an item value of 1 enables reading the writer's
ID. Each record read has a two-word header. The rst word indicates the type of
record:
0 Data record
1 Open record
2 Close record
The second word contains the writer's ID number. If the record is a data record,
the data follows the header. Open and close records contain no more information.
If the item value is 0, reading the writer's ID is disabled. Only data is read to the
reader's target area. The open and close records are skipped and deleted by the
le system when they come to the head of the message queue, and the two-word
header is transparent to the reader.
Default: 0
47
U16
Nondestructive read:
Applicable only if lenum species a message le.
If the item value is 1, the next FREAD by this reader does not delete the record.
Subsequent FREAD calls are unaected. When item is specied as 0, the next
FREAD deletes the record.
Default: 0
48
U32
Arm/disarm software interrupts:
Passes a value that arms/disarms the software interrupt mechanism (valid only if
lenum species a message le). To arm the le's software interrupt, pass the
external procedure label (NM plabel) or the interrupt procedure. To disarm the
software interrupt, pass a value of zero.
Command Definitions
4-103
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
51
Item Description
Append mode:
Enables or disables append mode based on the value of the item parameter.
Append mode is enabled if item is one (1) and disabled if item is zero (0). Write
operations append data at the end of a le while reads and seeks may occur
anywhere within the le when POSIX append mode is enabled for that le.
Append mode diers from opening a le for append access in several ways:
1
Append mode can be enabled and disabled while a le is open.
Append access is established when opening a le and cannot be
changed dynamically for a le number.
2
Append access is a process-local attribute aecting only the
access of the process open the le. Append mode aects all
processes sharing a logical record pointer. (The MULTI and
GMULTI options permits logical record pointers to be shared.)
3
A le's logical record pointer can be manipulated through
FPOINT or FREADDIR when append mode is active. Append
access prohibits logical record pointer operations. For example,
call to FPOINT and FSPACE result in an access violation for les
opened for append access .
This itemnum is supported only for byte stream les. If the le referenced by
lenum is not a byte stream le. FCONTROL will fail with a CCL condition code.
An error code of 42 (operation inconsistent with device type) is returned by
FCHECK when it is called following this FCONTROL error.
52
Set Nonblock
This option can be used to set and reset the Nonblock ag of a le. When the
Nonblock ag is true, any attempt to perform I/O to the le, results in the I/O
procedure returning without blocking. If the I/O can be performed without
blocking, then the I/O is completed normally. When Nonblock is false, I/O's will
block if necessary. The item parameter must be set to 1 in order to cause the
Nonblock ag to be set to true. A value of zero will reset the Nonblock ag. Any
other value fo the item parameter results in an error being returned.
The default value of item is 0.
Not all le types support this option.
53
Close File on Exec
This option allows the caller to set or reset closure of a specied le when a
POSIX exec( ) function is called. An item value of 0 causes the le remain
open on an exec( ). A value of 1 causes the le to close when an exec( ) is
performed. All other values of the item parameter return an FSERR 8 - ILLEGAL
PARAMETER VALUE error. The default value of item is 0.
4-104
Command Definitions
FCONTROL
Table 4-3. FCONTROL Itemnum/Item Values (continued)
Itemnum Mnemonic
54
Item Description
This item provides for compatibility with the ioct( ) function found in most
UNIX implementations. This option is only valid for streams and network socket
les and tape devices. Any attempt to use this option with other le types
results in an FSERR 8 - ILLEGAL PARAMETER VALUE error.
The item parameter must point to a structure that contains three ioctl( )
parameters:
Request
Arg
ioctl functional return
The rst 32 bits contain a short pointer to the arg parameter. The arg
parameter is pointed to by reference due to the variable length depending upon
the requested function. The last 32 bits of the structure contains the address of
the location to write the functional return. Due to the nature of the functional
return, this item is an output only address. In pascal, the structure is dened as
follows:
ioctl_parm_ptr = ^ioctl_parm_type;
ioctl_parm_type
request
arg
func_return
=
:
:
:
record
integer;
localanyptr;
localanyptr;
end;
The caller must correctly ll in the values of the structure before calling the
FCONTROL intrinsic. The functions that are supported through this option are
dened as standard documentation on the ioctl( ) function.
Note
Itemnums 10 through 41 are used in changing terminal characteristics.
Included with the denition of the code is an indication, where applicable,
of whether the characteristic is reset in break mode or after FCLOSE.
Characteristics that are reset in break mode are restored when there is a
RESUME from break mode.
Operation Notes
The FCONTROL intrinsic applies to les on disk, tape, terminal, or line printers. There are
some special conditions that exist when using FCONTROL with les on labeled magnetic tape.
Some FCONTROL functions cannot be used with labeled tapes, and other functions can produce
unexpected results. (Refer to itemnums 5, 6, 7, 8, and 9.)
Note
If you are performing control operations on terminal devices, refer to the
Asynchronous Serial Communications Programmer's Reference Manual
(32022-90002) for details on FCONTROL parameters specic to terminal control.
Command Definitions
4-105
FCONTROL
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
4-106
FWRITE, FDEVICECONTROL, RESETCONTROL, XCONTRAP
None
Accessing Files Programmer's Guide (32650-90017), Interprocess
Communication Programmer's Guide (32650-90019), MPE XL Asynchronous
Serial Communications Programmer's Reference Manual (32022-90012),
MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003
and 32650-90364), Using KSAM XL (32650-90168), and Trap Handling
Programmer's Guide (32650-90026)
Command Definitions
FDELETE
FDELETE
NM and CM callable.
Deactivates a specied logical record in an RIO le.
Syntax
I16V
I32V
FDELETE(lenum,lrecnum);
Parameters
lenum
16-bit signed integer by value (required)
lrecnum
Passes the le number of the le to be modied.
32-bit signed integer by value (optional)
Passes the relative logical record to be deactivated.
Operation Notes
If a record is not specied or the lrecnum is negative, the next logical record becomes inactive.
If the selected record has already been deactivated, CCE (2) is returned. Check to see if an
RIO record is inactive by calling the FCHECK intrinsic. An INACTIVE RECORD error indicates
that the record selected for the FDELETE was already inactive.
Only applicable for RIO les.
Not used for KSAM les.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred, but an inactive record may have been
encountered.
Request denied. An end-of-le (EOF) occurred.
Request denied. An access error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-107
FDEVICECONTROL
NM and CM callable.
Provides control operations to a printer, terminal, or a spooled device le and is used to:
Download character sets, forms, and internal or control tables used in printing.
Control the page size, pen positioning, form and use of character sets, the number of copies
to be printed, and all other printing environment characteristics.
Perform control operations on a terminal, printer, or spooled device le.
Syntax
I16V
UDS
I16V
I16V
FDEVICECONTROL(lenum,buer,length,controlcode
U16V U16V
U16
parm1,parm2,fserrorcode);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the device le.
user-dened structure (required)
Passes and returns device information:
Passes information to the device, such as character sets, forms, vertical
format control (VFC) information, or device control actions.
Returns device driver information.
length
(ASC) The buer is usually a 16-bit integer by reference or, for
controlcode=192, where parm=1, buer is a character array containing the
name of the terminal type or printer type le. Forcontrolcode=192, buer
values are dened in theparm1 discussion.
16-bit signed integer by value (required)
Passes the length of buer:
If positive, it indicates the length in half words.
If negative, it indicates the length in bytes.
(ASC) If controlcode=192, length is normally set to 1 unless parm1 is set
to 1 (specifying a new terminal or printer type le), then the length of the
array is specied in thelength parameter.
4-108
Command Definitions
FDEVICECONTROL
controlcode
16-bit signed integer by value (required)
Passes the item value to be returned. (Refer to Table 4-4.)
(ASC) Passes the number of the operation to be performed.Controlcode 192
is used to apply control directives to a device le.
parm1,
parm2
fserrorcode
Codes 0 through 64 call FCONTROL. Control passes to FCONTROL, and any
errors returned will have originated with FCONTROL.
16-bit unsigned integer by value (required)
Passes the value specied in the corresponding controlcode; there are several
values for parm1 and parm2 that dene the operation in more detail. (Refer
to Table 4-4.)
16-bit unsigned integer by reference (required)
Returns a le system error code number if an error occurs. If no error occurs,
fserrorcode is set to zero. If FDEVICECONTROL detects a bounds violation for
fserrorcode (that is, an address outside your stack area), fserrorcode is
returned unchanged.
Command Definitions
4-109
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values
Control- Mnemonic
code
128
I16V
Parm1,Parm2 Description
Character set selection:
parm1 (8:8)
Primary character set identication
parm2 (8:8)
Secondary character set identication
The Hewlett-Packard 268x page printer can contain up to 32 character sets,
allowing the use of a variety of fonts, styles, print rotations, and languages.
Controlcode =134 is used to download character sets to the printer or to select
any two downloaded character sets to be the current primary and secondary
character sets.
To change to the secondary character set (one character at a time), set the eighth
bit of the byte coding for the desired ASCII character. The Hewlett-Packard
268x strips out this bit and prints (in the secondary character set) the character
represented by the remaining 7-bit value. To change to the secondary character
set for a number of characters and over several lines, insert a 4CTRL54N5 (shift-in
character) in the data. Insert a 4CTRL54O5 (shift-out character) where the primary
character set is to be reactivated.
129
I16V
Logical page activation/deactivation request:
parm1 (0:1)
0 = Ignore the left byte of parm2 .
1 = Deactivate the logical page table entry identied in the left
byte of parm2 .
parm1 (1:1)
0 = Ignore the right byte of parm2 .
1 = Activate the logical page table entry identied in the right
byte of parm2 .
parm2 (0:8)
Logical page table entry (0 to 31) to be deactivated. Ignored if
parm1 (0:1)=0.
parm2 (0:8)
Logical page table entry (0 to 31) to be activated. Ignored if
parm1 (1:1)=0.
Logical pages being printed can be canceled or enabled through the activation or
deactivation of those pages.
Every physical page is composed of one or more logical pages. When the
Hewlett-Packard 268x begins to print each physical page, it scans the logical page
table (LPT) for the rst logical page labeled as ACTIVE. The printer then
continues searching the table sequentially for active pages and printing them
until it has printed the last active page. At this point, the Hewlett-Packard 268x
performs a physical page eject and starts the sequence again. There must be at
least one active LPT entry while the Hewlett-Packard 268x is printing.
4-110
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
130
I16V
Parm1,Parm2 Description
Relative pen displacement:
parm1
A 16-bit signed integer containing the desired X-axis
displacement, in dots, of the pen from its current position.
parm2
A 16-bit signed integer containing the desired Y-axis
displacement, in dots, of the pen from its current position.
No pen movement results from requests to move the pen o the logical page.
Because the coordinate system is based upon the current logical page itself and
not upon the page's orientation with respect to the printer, do not consider how
the page has been rotated when assigning displacement values to parm1 and
parm2 . Since the dot density for the Hewlett-Packard 2680 (180 dots per inch)
diers from the Hewlett-Packard 2688 (300 dots per inch), the eects of parm1
and parm2 are dierent.
131
I16V
Absolute pen move:
parm1
An integer containing the X-coordinate, in dots, of the point to
move the pen.
parm2
An integer containing the Y-coordinate, in dots, of the point to
move the pen.
The values in parm1 and parm2 are measured from the upper left corner of the
logical page. Do not take page rotation into account when assigning coordinates
as the printer does not move the pen if the location specied is o the logical
page. Since the dot density for the Hewlett-Packard 2680 (180 dots per inch)
diers from the Hewlett-Packard 2688 (300 dots per inch), the eects of parm1
and parm2 are dierent.
132
I16V
Dene job characteristics:
parm1 (0:1)
0 = Ignored
1 = Printer does not print job separation marks until next open
job
parm1 (1:1)
0 = Ignored
1 = Parm2 contains maximum allowable number of copies
parm2
Signicant only if parm1 (1:1)=1 (Species the maximum
number of copies the printer makes, for any one page, for the
current job. The default maximum is 32,767.)
Command Definitions
4-111
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
133
I16V
Parm1,Parm2 Description
Dene physical page.
The following bits are ignored if set to zero:
parm1
parm1
parm1
parm1
parm1
parm1
parm1
parm1
parm1
(0:1)
1 = Multicopy form overlay feature on
(1:1)
1 = Multicopy form overlay feature o
(2:1)
1 = Reserved for the operating system
(3:1)
1 = Redene physical page length
(4:1)
1 = Redene number of copies per page
(5:1)
1 = Reserved for the operating system
(6:1)
1 = Reserved for the operating system
(7:1)
1 = Reserved for the operating system
(8:8)
New physical page length in units of 0.25 inches; cannot be less
than 3.0 inches (a value of 12) or greater than 17.0 inches (a
value of 68)
parm2
Number of copies to print; if number exceeds the maximum
dened in parm2 ofcontrolcode 132, only the maximum
number of copies is printed
FDEVICECONTROL accepts page length values that are in multiples of 0.25 inches,
but the Hewlett-Packard 268x printer is able to produce only pages that are
multiples of 0.5 inches. For this reason, use only even values in parm1 (8:8) (bit
(15:1)=0).
134
I16V
Download/delete character set:
parm1 (0:1)
0 = Download character set identied in right-hand byte of
parm2 , Hewlett-Packard 268x
1 = Purge character set identied in right-hand byte of parm2 ,
Hewlett-Packard 268x
parm2 (0:1)
0 = First record of a load
1 = Continuation of previous record
parm2 (8:8)
Character set identier; integer from 0 to 31
If there is an attempt to download a character set having the same identier as
one existing in the printer, then the Hewlett-Packard 268x purges the existing
character set and repacks the user area before loading the new font. However,
before the modication of the user area, the Hewlett- Packard 268x prints all
data currently in its buer, as it does when a character set, form, or vertical
format control set (VFC) is loaded, overlayed, or deleted.
4-112
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
135
I16V
Parm1,Parm2 Description
Download/delete form:
parm1 (0:1)
0 = Load form set identied in the right-hand byte of parm2
1 = Purge identied form set from the Hewlett-Packard 268x
printer's memory
parm2 (0:1)
0 = First record of a load
1 = Continuation of previous record
parm2 (8:8)
Form set identier; integer from 0 to 31
If attempting to download a form set having the same identier as one existing in
the printer, then the Hewlett-Packard 268x purges the existing form set and
repacks the user area before loading the new form. However, before the
modication of the user area, the Hewlett-Packard 268x prints all data currently
in its buer, as it does whenever you load, overlay, or delete a character set,
form, or vertical format control set (VFC).
136
I16V
Download logical page table:
parm1
parm2 (0:1)
Not used
0 = First record of a load
1 = Continuation of previous record
A logical page is a page of data that may take up an entire sheet of paper. It is
possible to print up to eight logical pages on one physical page. The logical page
table, 513 words long, contains some of the information needed to print up to 32
logical pages, so that the set of up to eight logical pages printed on any one
physical page can be varied.
137
I16V
Download multicopy form overlay table:
parm1
Not used
parm2
Not used
Prints up to eight copies of a page, each on one or two dierent forms.
FDEVICECONTROL downloads into the printer's memory a table containing one
word of information for each of the eight possible copies to be overlaid with a
form. The format of each word of the table is:
Bit (0:1)
0 = Ignored
1 = Overlay form1 on physical page
Bit (1:1)
0 = Ignored
1 = Overlay form2 on physical page
Bits (2:4)
Reserved for the operating system
Bits (6:5)
Form1 identier; integer from 0 to 31
Bits (11:5)
Form2 identier; integer from 0 to 31
Command Definitions
4-113
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
138
I16V
Parm1,Parm2 Description
Download/delete vertical format control (VFC);
parm1 (0:1)
0 = Load VFC
1 = Delete VFC
parm2 (0:1)
0 = First record of a load
1 = Logical continuation of the previous record
parm2 (8:8)
VFC set identier; integer from 0 to 31
The VFC table is an ASCII le downloaded to the Hewlett-Packard 268x printer
in order to give specic instructions on the print density, location of the top of
the page, the bottom of the page, and other specications of the printed page.
The Hewlett-Packard 268x expresses the height of a printed line in dots and the
system uses this value to compute line positions on the page. Because these space
measurements are relative to the top of the logical page, as opposed to the
physical page, use the same or dierent VFC tables for logical pages of dierent
rotations.
139
I16V
Download/delete a picture:
parm1 (0:1)
0 = Load picture
1 = Delete picture
parm2 (0:1)
0 = First record of a load
1 = Logical continuation of the previous record
parm2 (8:8)
Picture identier; integer from 0 to 31
When the picture is downloaded to the Hewlett-Packard 268x, it changes every
pointer to reect where the dot per bit symbol actually is in memory. If a picture
is downloaded and one is already present with the same identier (0-31), then the
original one is overwritten in the picture descriptor block (PDB). The area taken
up by the deleted picture is freed as soon as the page has been transferred to
paper.
140
I16V
Page control:
parm1 (15:1)
0 = Do not eject physical page
1 = Eject physical page before going to logical page (no eect if
the rst record since an environment load, FOPEN/FCLOSE )
parm1 (13:2)
Auto-eject mode:
00 = Use auto-eject ag of last data record (default at start;
auto-eject enabled)
01 = Enable auto-eject (select VFC channel 1 on new page)
11 = Disable auto-eject (position pen at top of page)
parm2 (8:8)
Logical page number; integer from 0 to 31
The logical page identied in parm2 becomes the current logical page even if
other logical pages have entries that precede it in the logical page table.
FDEVICECONTROL activates the specied page if it is inactive, and the
Hewlett-Packard 268x performs a physical page eject if parm1 (15:1)=1.
4-114
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
141
I16V
Parm1,Parm2 Description
Clear environment:
When set to zero, the following bits are ignored.
parm1 (0:1)
1 = Clear all character sets
parm1 (1:1)
1 = Clear all forms
parm1 (2:1)
1 = Clear all vertical format controls (VFCs)
parm1 (3:1)
1 = Clear all pictures
parm2
Not used
The printer ushes all data currently in its buers and then performs the
indicated clears, if any.
142
I16V
Reserved for the operating system
143
I16V
Load default environment:
parm1
parm2
Not used
Not used
The Hewlett-Packard 268x printer ushes all data, erases the user area, and loads
the default character set, the vertical format control (VFC), and the logical page
table (LPT).
144
I16V
Print picture:
parm1 (0:1)
0 = Temporary picture
1 = Addressable picture
parm1 (1:1)
0 = X and Y relative to the current pen position
1 = X and Y are absolute pen position to the logical page
parm1 (2:14)
parm2 (0:1)
X coordinate for picture placement (radixed integer)
parm2 (1:1)
Not used
0 = First temporary picture load
1 = Continuation record for load
Command Definitions
4-115
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
145
I16V
Parm1,Parm2 Description
End of job:
parm1
parm2
146
148
I16V
I16V
Not used
Not used
Device extended capability mode:
parm1
0 = Clear
1 = Set
parm2
Not used
Device Status:
Enable, disable, or return various types of extended device status. In order to
maintain backward compatibility with MPE V/E, the initial setting (after rst
FOPEN of device) is set to disable all status reporting. Any application that
requires status reporting must enable status reporting after opening the device.
Status reporting is a global device feature, either every accessor sees it or does
not see it.
When enabled, device related I/O errors (if they occur) are not returned. The
caller is notied that the device has status and another FDEVICECONTROL call has
to be made to determine the status.
When enabling status, the buer returns the number of bytes occupied by the
largest status block returned by the device. This number is returned in a 32-bit
integer, and the count must be set to at least 4 bytes; otherwise, a bounds
violation occurs.
When nowait I/O is enabled, FWRITE does not notify the caller that status is
available. The application is notied that the status is available after calling
IOWAIT or IODONTWAIT.
The status return can be either a wildcard (return any available status) or a
specic type:
param1
0 Any available and enabled status
1 Device status
2 Environment status
3 Job status
4 Job error log status
parm2
0 Return last buered status
1 Return new actual status
2 Enable status specied in param1
3 Disable status specied in param1
4-116
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
149
I16V
Parm1,Parm2 Description
Set data block number:
To be used for printer error recovery. The data block number is used as the
printing application/utility data index. The printing application can set data
block numbers allowing it to return to that place in the data stream and
retransmit data from that point forward.
parm1
parm2
150
I16V
Lower half of the 32-bit integer
Upper half of the 32-bit integer
Start silent run:
Used to start printer recovery from specic error conditions on recoverable devices
or to backup or skip forward a specied number of pages and resume printing.
parm1
parm2
151
I16V
Start silent run physical page number
Resume printing of physical page number
Print standard header or trailer:
Used to print standard headers/trailers. If headers/trailers are disabled through
the BANNERS, HEADON, or HEADOFF commands, this control code is invalid.
PM (privileged mode) is required to use this option.
The le system does not perform printer setup/reset functions before or after
printing the banner; therefore, the caller must place the printer and paper in the
proper state before and after calling this control code.
parm1
0 Print standard header
1 Print standard trailer
parm2
Not used, must be set to zero
Command Definitions
4-117
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
U16V
Parm1,Parm2 Description
Perform control functions on terminal device les:
parm1
Indicates the specic control directive applied to the terminal device le
being accessed. For printers, onlyparm1=1 is supported. Valid values
are:
1
Specify terminal type or printer type le:
Species a new terminal type or printer type le for use with a
device. The specied le may be created through the TTUTIL
utility. The name of the terminal type or printer type le is passed
in buer , with the length of buer set through the length
parameter. If this call is issued against a device connected through
PAD, CCE (2) is returned and the terminal or printer type
associated with the device is changed, but the device operates as if
no device control action took place.
2
Set read timeout value for next read:
Sets a timeout value to be applied to the next read request in
seconds. If the timer expires before the next read is terminated,
the read data is transferred to the buer and the read reply
returns a software timeout error status with length =0. For reads
posted to devices connected through PAD, add enough time to
compensate for delays caused by the network.
3
Set line speed for the device:
Set the line speed for the device associated with lenum by
entering a new line speed, representing characters per second, as
the value of buer . Supported speeds are 30, 120, 240, 480, 960,
and 1920 characters per second. Input and output line speeds are
the same. If this call is issued against a device connected through
PAD, the terminal control action is ignored and a meaningless
value is returned.
4
Set echo ON/OFF at terminal:
Enable or disable read data echo to a terminal through the DTC.
Valid values are:
0 Echo o
1 Echo on
This call is not valid if the terminal is operating in binary or block
mode.
4-118
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 5
Cont'd
Set system break response on or o at a terminal:
Enable or disable system response to the entry of a system
4BREAK5 at the terminal. Valid values are:
0 Disable break
1 Enable break
6
Set subsystem break response on or o at a terminal:
Enable or disable system response to the entry of a subsystem
break character at the terminal. Valid values are:
0 Disable subsystem break
1 Enable subsystem break
If the terminal is connected through PAD, the subsystem break
must be followed by a 4RETURN5 to signal PAD that data is to be
forwarded.
8
Obtain time used for completion of last read:
Determine the time, in seconds, required for the last read to
complete. Ensure that this call is placed immediately after the
read to be timed, with no subsequent reads in between. Only read
access is allowed for this request. All reads are timed, so there is
no need to enable the timer.
9,11 Set parity generation and checking on or o:
Enable or disable parity generation and checking between the
driver and device. Valid values are:
0 Disable parity; all eight bits of each character are passed
through.
1 Enable parity; type of parity specied by the parity setting is
in eect.
Input and output parity is the same. If issued for a terminal
connected through PAD, CCE (2) is returned, but no terminal
control action occurs.
Command Definitions
4-119
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 10, Set type of parity:
Cont'd 12
If parity is enabled, this request determines what kind of parity is
computed when parity is checked:
0 No parity check on input, eighth bit set to 0 on output (parity
type = zeros)
1 No parity check on input, eighth bit set to 1 on output (parity
type = ones)
2 Even parity checked on input, even parity generated on output
(parity type = even)
3 Odd parity checked on input, odd parity generated on output
(parity type = odd)
If parity is disabled, no parity is used.
If issued for a terminal connected through PAD, CCE (2) is
returned, but no terminal control action occurs.
14
Set line deletion response:
Enables or disables the transmission of line deletion characters
(!!!) to the terminal after a user cancels a line at a terminal:
0 Disable transmission
1 Enable transmission
Line deletion characters are not output by PAD devices. If issued
to a terminal connected through PAD, CCE (2) is returned, but
no terminal control action occurs.
4-120
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 15
Cont'd
Set transparent editing mode:
Enables or disables transparent (unedited) mode. When enabled,
allows most special characters to be read and treated as data and
a small subset to retain their meaning:
AEOR
The AEOR character dened through a previous call
to FCONTROL itemnum =25. The read terminates in
error, and a call to FCHECK returns an error code of
31. The AEOR character is passed with the data
and included in the byte count.
4BREAK5
Causes a system break (when enabled) and transfers
control to the system. If the RESUME command is
entered, transparent editing is resumed.
4CTRL5Q
The resume output character of the XON/XOFF
handshake. This character is stripped from the input
data when XON/XOFF protocol is enabled.
DC2
When input as the rst character, it is stripped out.
A DC1 (4CTRL5Q) is written to the terminal. If not
input as the rst character, DC2 is a data character.
4CTRL5S
The stop output character of the XON/XOFF
handshake. This character is stripped from the input
data when XON/XOFF protocol is enabled.
(DC1 or
XON)
(DC3 or
XOFF)
Enable transparent editing by passing non-NUL characters for the
subsystem break and EOR characters in the buer in the following
format:
bits Species the character to be used as the subsystem break
(0:8) character. Any character not dened as a special character
in transparent mode (including the standard subsystem
break character) can be used. If set to 0, subsystem break is
disabled.
bits Species the character to be used as the line termination
(8:8) character (EOR). Any character not dened as a special
character in transparent mode can be used.
Disable transparent editing by passing NUL characters.
If used for a device connected through PAD, data is not forwarded
from the terminal immediately after the characters dened as the
subsystem break or EOR character are typed. The terminal user
has to press 4RETURN5 to cause data to be transmitted, or wait for
the data forwarding timer to expire (if set). The host software
recognizes and acts on the characters dened in this call.
Command Definitions
4-121
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16v
Parm1,Parm2 Description
parm1 26
Cont'd
Device XON/XOFF:
Enable or disable XON/XOFF ow control between the device
and the DTC:
1 Enable device XON/XOFF
0 Disable device XON/XOFF
When enabled, the DTC stops sending data to the device when
XOFF is received and resume when XON is received. XON/XOFF
characters are not sent to the host.
When disabled, the XON/XOFF characters are not treated as
control characters, but are passed to the host as data. When
disabled, data overruns can occur.
27
Set XOFF timer value:
Enable or disable the XOFF timer.
To enable the XOFF timer, pass a positive value, representing
time in seconds, in the buer parameter. The XOFF timer causes
a warning message to be sent to the console if a device is XOFFed
for a time exceeding the set limit.
To disable the XOFF timer, pass a 0 or negative value in the
buer parameter.
If issued to a terminal connected through PAD, CCE (2) is
returned, but no terminal control action occurs.
28
Block mode types supported:
This is a read only request that returns a value representing the
type of block mode supported by the driver. Valid values are:
6 DTC style page block mode
7 Line and DTC style page block mode
15 PAD terminal supporting page block mode
4-122
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 29
Cont'd
Block mode alert character:
Species the character used to signal Hewlett-Packard block mode
transfers. The standard alert character is DC2. This call only
denes the alert character; it does not enable Hewlett-Packard
block mode.
If issued to a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
30, Read trigger and block mode trigger character:
32
Specify which character the DTC should send to trigger a
character mode or block mode read on a device. The standard
trigger character is DC1. If a NUL character is specied, there is
no trigger character.
If issued to a terminal connected through PAD, CCE (2) is
returned but the device control action does not occur.
36
Backspace character:
Species which character will be a backspace in standard editing
mode.
Default: backspace
37
Cancel line character
Species which character will be a line deletion character in
standard editing mode.
Default: 4CTRL5X
39
Type 1 EOR character:
Species the EOR character to be used in standard or transparent
editing mode. This value is passed in the high order byte (value *
256) of buer . If issued to a terminal connected through a PAD,
the new EOR character (non-carriage return) must be followed by
a carriage return to instruct the PAD to transmit the data. Use a
null character to disable the character.
Default: 4Return5
40
Type 2 EOR character (AEOR):
Species the AEOR character and enables its use. This value is
passed in the high order byte (value * 256) of buer . Any
character can be specied, but do not use any special characters
(refer to FCONTROL itemnum =25 for details). If issued to a
terminal connected through a PAD, the new EOR character
(non-carriage return) must be followed by a carriage return to
instruct the PAD to transmit the data. Use a null character to
disable the AEOR character.
Command Definitions
4-123
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 41
Cont'd
Subsystem break character:
Species the character is to be used as the subsystem break
character. This value is passed in the high order byte (value *
256) of buer .
If issued to a terminal connected through PAD, the new
subsystem break character is recognized by the host, but the
terminal user has to press 4RETURN5 following the subsystem break
to signal the PAD that data is ready to be transmitted.
51
Set typeahead mode:
Enable or disable typeahead mode:
0 Disable typeahead mode; accept read data from the device as
it is posted. The terminal user must wait for a new read to be
posted before entering additional data. (default)
1 Enable typeahead mode; pass read data from the device to a
typeahead buer (up to 224 characters). The terminal user
can enter data before a read has been posted. Typeahead is
not supported on PAD terminals. If issued for a terminal
connected through PAD, CCE (2) is returned, but the device
control action does not occur.
52
Form feed in output data:
Species whether the form feed character is replaced in the
carriage control of terminals:
0 Replace form feeds with a form feed replacement character
1 Form feed allowed
53
Dene form feed replacement character:
Species the character that replaces the form feed character in the
terminal carriage control when form feed replacement is enabled.
The form feed in carriage control is replaced; form feed in data is
not replaced. A default of NUL is used if form feed replacement is
enabled and no replacement character is specied.
4-124
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 55
Cont'd
Backspace response action:
Selects the action the DTC takes when it receives a backspace
character. Valid values are:
1 Remove character from input and back cursor up one space
(default)
5 Remove character from input and erase character (backspace,
space, backspace)
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
56
Data bits per character:
Species whether 7-bits or 8-bits are used for each character.
If 7-bits is selected, parity generation and checking is controlled by
the current parity setting. If the current parity is set to \no
parity" or parity checking is disabled, parity is not in eect.
If 8-bits is selected, parity is set to \no parity" and the current
parity setting is saved, so when the user switches back to 7-bits,
parity is returned to its previous setting.
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
57
Subsystem break character:
Returns the current subsystem break character.
60
Flush typeahead buer:
Valid values are:
1 Flush the typeahead buer before the next read is started.
Any data in the typeahead buer is lost. Valid for the next
read only.
0 Disable the request.
Flush typeahead is enabled only if typeahead is enabled.
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
Command Definitions
4-125
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
192
Cont'd
U16V
Parm1,Parm2 Description
parm1 61
Cont'd
Bypass typeahead buer: Valid values are:
1 The next read is taken from the device, and any information
currently in the typeahead buer is bypassed. The data in the
typeahead buer is not ushed, and can be obtained by a
subsequent read. The request is valid for the next read only.
0 Disable the request.
This request is valid only if typeahead is enabled.
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
62
Quiesce I/O: Valid values are:
1 The control will not complete until all previous I/O to the
device has completed. If issued against a terminal connected
through a PAD, control issues only previous I/O sent to PAD
and not to the device.
63
Single echo mode in typeahead: Valid values are:
1 Enables single echo. Typeahead data will be echoed only when
the read is posted.
0 Disable the request. Typeahead data will be echoed when
entered and when the read is posted (default mode).
This request is valid only if typeahead is enabled.
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
64
Ignore parity error on input: Valid values are:
1 Parity errors will be ignored.
0 Parity errors will be reported (default).
If issued against a terminal connected through PAD, CCE (2) is
returned, but the device control action does not occur.
parm2
Indicates the read and write access for the operation being performed.
Set parm2 to one of the following values:
1
Read only; return current information
2
Write only; pass new information
3
Read/Write; pass new information and return valid information
before call
Information is returned in the area pointed to by the buer parameter.
For detailed information, refer to the Asynchronous Serial
Communications Programmer's Reference Manual (32022-90002).
4-126
Command Definitions
FDEVICECONTROL
Table 4-4. FDEVICECONTROL Controlcode/Parm1,Parm2 Values (continued)
Control- Mnemonic
code
193
I16V
Parm1,Parm2 Description
Record processing information for NRJE spoolles:
parm1
Indicates the character code (for example, ASCII) of spoolle
data. Refer to SNA NRJE Network Remote Job Entry
User/Programmer Reference Manual (30245-90001).
parm2 (14:1)
0 = Data not compacted
1 = Data compacted
parm2 (15:1)
0 = Data not compressed
1 = Data compressed
Command Definitions
4-127
FDEVICECONTROL
Table 4-5. FDEVICECONTROL Controlcode 192 Values
Parm1
Parm2
1
R/W
Specify terminal or printer type le
2
R/W
Set read timeout value for the next read
3
R/W
Set the line speed for the device
4
R/W
Set echo ON/OFF at a terminal
5
R/W
Set system break response ON/OFF at a terminal
6
R/W
Set subsystem break response ON/OFF at a terminal
8
R
9
R/W
Set parity checking ON/OFF
10
R/W
Set type of parity to check
11
R/W
Set parity generation ON/OFF
12
R/W
Set type of parity generated
14
R/W
Set line deletion response
15
R/W
Set transparent editing mode
26
R/W
Device XON/XOFF enable
27
R/W
Set XOFF timer value
28
R
29
R/W
Dene block mode alert character
30
R/W
Dene block mode trigger character
32
R/W
Dene read trigger character
36
R/W
Dene backspace character
37
R/W
Dene cancel line character
39
R/W
Dene type 1 EOR character
40
R/W
Dene type 2 EOR character (AEOR)
4-128
Command Definitions
Description
Obtain time used for completion of the last read
Block mode types supported
FDEVICECONTROL
Table 4-5. FDEVICECONTROL Controlcode 192 Values (continued)
Parm1
Parm2
Description
41
R/W
Dene subsystem break character
51
R/W
Set type ahead mode
52
R/W
Form feed allowed in output data
53
R/W
Dene form feed replacement character
55
R/W
Select backspace response action
56
R/W
Specify data bits per character
57
R
60
R/W
Flush typeahead buer
61
R/W
Bypass typeahead buer
62
W
63
R/W
Single echo mode typeahead
64
R/W
Ignore parity error
Obtain subsystem break character
Quiesce I/O
Operation Notes
Not used for KSAM les.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
FCONTROL
None
Accessing Files Programmer's Guide (32650-90017), IFS/3000 Reference
(36580-90001), and MPE XL Asynchronous Serial Communications
Programmer's Reference Manual (32022-90012)
Command Definitions
4-129
FERRMSG
NM and CM callable.
Returns a message corresponding to an FCHECK error number and enables error messages to be
displayed from a program.
Syntax
I16
CA
I16
FERRMSG(fserrorcode,msgbuer,msglength);
Parameters
fserrorcode
16-bit signed integer by reference (required)
msgbuer
Passes an error code returned by the FCHECK intrinsic indicating which
message to return in msgbuer.
character array (required)
msglength
Returns the error message identied with fserrorcode. To contain the
longest possible message, msgbuer must be >= 72 bytes long.
16-bit signed integer by reference (required)
Returns the length of the error message in msgbuer. The length is returned
in positive bytes.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. No error message exists for this fserrorcode.
Request denied. The msgbuer address was out of bounds, msgbuer was
not large enough, or msglength was out of bounds.
Related Information
Intrinsics
Commands
Manuals
4-130
None
None
Accessing Files Programmer's Guide (32650-90017).
Command Definitions
FFILEINFO
FFILEINFO
NM and CM callable.
Returns information about a le.
Syntax
I16V
I16V
*
FFILEINFO(lenum[,itemnum,item] [...]);
Note
Up to ve itemnum/item pairs can be specied.
Parameters
lenum
16-bit signed integer by value (required)
itemnum
Passes the le number of the le for which information is requested.
16-bit signed integer by value (optional)
item
Species which item value is to be returned. (Refer to Table 4-6.)
type varies (optional)
Returns the value of the item specied in the corresponding itemnum . (Refer
to Table 4-6.)
Command Definitions
4-131
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values
Item Description
Itemnum Item
Type
1
CA
File designator (28 bytes):
Returns the le designator of the le being referenced in the format:
lename.groupname.accountname
Must be >=28 bytes in length. Unused bytes are lled with right-justied blanks
and a nameless le returns an empty string. The fully qualied name of the le
referenced by lenum is returned as the value of this itemnum . Only names
which can be expressed using MPE-only semantics are returned by this itemnum .
If the name of the object referenced by lenum can not be expressed using
MPE-name semantics a CCL condition code is returned. Calling FCHECK for
lenum after this error occurs will return FSERR391.
2
U16
File options:
Returns le characteristics (refer to the foption gure). The record format
extension bit is returned as the foption (1:1) bit. Byte stream record format is
represented as a record format extension of one with a variable record format
foption (8:2) bits equal to 01.
Directories, symbolic links, device links, pipes and FIFO's can not be represented
by foptions . If the object referenced by lenum is one of these objects, a CCL
condition code is returned. Calling FCHECK for lenum after this error occurs will
will return FSERR399
3
U16
Access options:
Returns le access information (refer to the Faoption gure).
4
I16
(CM) Record size: Returns the logical record size associated with the le:
If the le was created as a binary le, this value is positive and is in half words.
If the le was created as an ASCII le, this value is negative and is in bytes.
For message les, when there is call to FCONTROL with controlcode =46, the value
returned is the size of the data records, including the 4 byte header.
Maintained for compatibility with MPE V/E-based systems only. CM record
sizes are imposed when FGETINFO returns record size information on all le types.
If the record size exceeds the limits, a zero is returned.
Note: If a zero is returned, use item 67.
5
I16
Device type/subtype:
Returns the type and subtype of the device being used for a KSAM, RIO,
circular, or message le, or devices such as a tape drive, printer, or terminal where
bits (0:8) indicate the device subtype, and bits (8:8) indicate the device type.
If the le is not spooled or is opened as a spoolle through the logical device, the
actual value is returned. If an output le is spooled and was opened by device
class name, the type and subtype of the rst device in its class is returned. (This
may be dierent from the device actually used.)
4-132
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
6
U16
Logical device number:
Returns the logical device number of the device where the disk le label resides.
If the le is a disk le, the LDEV is the location of the le label. (File data can
reside on the same device as the le label.)
If the le is spooled, the LDEV is a virtual device number that does not
correspond to the system conguration I/O device list.
If the le is located on a remote computer, linked by a DS point-to-point or
X.25 link, the left eight bits (0:8) are the LDEV of the distributed system (DS)
device.
If the le is located on a remote computer, linked by NS 3000/XL, the left
eight bits (0:8) are the remote environment of the connection. The right eight
bits (8:8) are the LDEV of the device on the remote computer where the le
label resides.
If the DS device for the RFA or the LDEV is 0, then a zero is returned.
Note: If a zero is returned, use item 50.
7
U16
Hardware device address:
Returns 2048. Maintained to provide backward compatibility with MPE
V/E-based systems.
8
I16
File code:
Returns the le code of a disk le (refer to FFILEINFO for le codes).
9
I32
Current logical record pointer:
Returns the current logical record pointer setting. This value is the displacement
in logical records from record number 0 in the le and identies the record that
would be accessed next by FREAD or FWRITE.
10
I32
EOF:
Returns the pointer setting of the last logical record currently in the le
(equivalent to EOF). If the le does not reside on disk, the value is zero. For
message les, when a call is made to FCONTROL with itemnum =46, the number of
records returned includes open, close, and data records.
11
I32
File limit:
Returns a number representing the last logical record that can exist in the le
(equivalent to the le limit). If the le does not reside on disk, the value is zero.
12
I32
Log count:
Returns the logical records passed to and from the program during the current
le access.
13
I32
Physical count:
Returns the number of buered physical I/O operations performed since the last
FOPEN/HPFOPEN call (records).
Command Definitions
4-133
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
14
I16
Block size:
Returns the le block size:
If the le is binary, the value is positive and the size is in half words.
If the le is ASCII, the value is negative and the size is in bytes.
For standard xed ASCII les with odd record sizes, the block size is computed
as \(record size + 1)" X block factor. For even record sizes, it returns the block
size from the gufd.
Maintained for compatibility with MPE V/E-based systems only. CM block size
limits are used when FGETINFO returns block size information on all le types
(STD, KSAM, RIO, CIR, MSG). If the block size of the specied le exceeds the
limits, zero is returned.
Note: If a zero is returned, use item 68.
15
I16
Extent size:
Returns the extent size; for compatibility with MPE V/E-based systems only.
Note: If a zero is returned, use item 69. If extent size is specied or the
maximum number of extents is specied at le creation, the size and number of
extents are determined by the operating system and the item values are not
actual values; they are calculated using system defaults.
16
U16
Maximum number of extents:
If the extent size or maximum number of extents is specied as zero at le
creation, then the size and number of extents are determined by the system. In
that case, these item values are calculated using system defaults defaults and do
not reect actual values.
17
I16
User labels:
Returns the number of user labels dened for the le during creation. If the le is
not a disk le, this number is zero. When an old le is opened for overwrite
output, the value is not reset and the old user label is not destroyed.
18
CA
Creator:
Returns the name of the le creator (at least 8 bytes). If the le does not reside
on disk, blanks are returned.
An unqualied form of the le owner's name is returned as the value of this
itemnum . The le owner is not neccessarily the le's creator. File ownership may
be changed using the :ALTFILE command.
A symbolic zero (ASCII 48 in decimal) is returned as the le owner for root
directories, accounts, and MPE groups created prior to release 4.5 of MPE/iX.
If the le is not located in the account in which the le owner is a member, a
blank le owner name is returned. Item number 85 should be used to obtain the
full le owner name instead of item 18.
4-134
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
19
I32
Label address:
Returns a zero. For compatibility with MPE V/E-based systems only.
20
I16
Blocking factor
21
I16
Physical block size; indicates half words
22
I16
Data block size; indicates half words
23
I16
Oset to data in blocks; indicates half words
24
I16
Oset of active record table for RIO les; indicates half words
25
I16
Size of active record table within the block; indicates half words
26
CA
Volume ID (tape label)
27
CA
Volume set ID (tape label)
28
U16
Expiration date (calendar format)
29
I16
File sequence number
30
I16
Reel number
31
I16
Sequence type
32
U16
Creation date (calendar format)
33
I16
Label type
34
I16
Current number of writers
35
I16
Current number of readers
36
U16
File allocation date, when the le was last restored (CALENDAR format)
37
I32
File allocation time, when the le was last restored (CLOCK format)
38
U16
Spoolle device le number:
Bits (1:15) = Device le number
Bit (0:1) = 1 Output spoolle
Bit (0:1) = 0 Input spoolle
If the spoolle device number is larger than 32767, itemnum 38 returns 0 (zero).
Use itemnum 78 instead for spoolle numbers larger than 32767.
40
I32
Disk device status:
Returns a zero. For compatibility with MPE V/E-based systems only.
Command Definitions
4-135
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
41
I16
Device type
42
I16
Device subtype
43
CA
Environment le name (>=36 bytes)
44
I16
Number of disk extents currently allocated to the le
45
CA
File name from labeled tape header 1 record (>= 17 bytes)
46
I16
Tape density
47
I16
DRT number:
Always returns an 8.
48
I16
Device unit number:
Always returns a 0.
49
U16
Equivalent to a software interrupt PLABEL for message les
50
U16
Real device number of the le
51
I16
Remote environment number
Note: If using NS 3000/XL RFA (remote le access), specify DSDEVICE ldev#
when you are using a DS (point-to-point or X.25) link.
52
I32
Last modication time (CLOCK format)
Zero is returned as the modication time for root directories, accounts, and MPE
groups created prior to release 4.5.
53
U16
Last modication date (CALENDAR format)
Zero is returned as the modication time for root directories, accounts, and MPE
groups created prior to release 4.5.
54
U16
File creation date (CALENDAR format)
Zero is returned as the modication time for root directories, accounts, and MPE
groups created prior to release 4.5.
55
U16
Last access date (CALENDAR format)
Zero is returned as the modication time for root directories, accounts, and MPE
groups created prior to release 4.5.
4-136
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
56
I32
Number of data blocks in a variable length le
57
I16
Number of user labels written to the le
58
I16
Number of accessors having output access (write) for a particular le
59
I16
Number of accessors having input access (read/update) for a particular le
60
I16
Terminal type:
0
1
2
3
4
5
61
CA
File's associated device not a terminal
Standard hardwire or multipoint terminal
Terminal connected through phone-modem
DS pseudo-terminal
X.25 Packed Switching Network PAD (packet assembler/disassembler)
terminal
NS virtual terminal
NS 3000/XL remote environment ID name
Note: If using NS 3000/XL RFA (remote le access), specify DSDEVICE ldev#
when using a DS (point-to-point or X.25) link. A buer must be provided for the
node name (or envid ) with the required space of 52 bytes; otherwise, data
corruption may occur on variables following itemnum =61 or an FSERR 73,
BOUNDS VIOLATION may be returned.
62
CA
File lockword (8 bytes):
63
CA
Unique le identier (UFID) (20 bytes):
64
@64
Virtual address of the le:
Applicable for standard disk les only. (Requesting itemnum s 64, 74, or 75 for
any other le type, RIO, MSG, CIR, causes an error and returns CCL (1).)
65
66
Reserved for the operating system.
@32
Virtual address of global unique le descriptor (GUFD):
Command Definitions
4-137
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
67
U32
(NM) Record size (indicates bytes)
68
U32
Block size (indicates bytes). Odd or even record sizes are returned as the block
size from the gufd.
69
U32
Extent size (indicates bytes)
74
@64
Virtual address of le label:
Applicable for standard disk les only. (Requesting itemnum s 64, 74, or 75 for
any other le type (RIO, MSG, CIR) causes an error and returns CCL (1).)
75
CA
Hardware path:
Applicable for standard disk les only. (Requesting itemnum s 64, 74, or 75 for
any other le type (RIO, MSG, CIR) causes an error and returns CCL (1).)
76
CA
Volume restriction (34 bytes):
The last two characters indicate the type:
77
U32
0
File placed on the specied volume at creation
1
File can be placed on any volume containing the specied class at creation
2
File can be placed on any volume within the specied volume set at
creation (Default)
Transaction management log set ID
If itemnum 77 = 0 (zero), the le is not attached to the XM (Transaction
Management) log.
78
U32
Spoolle device le number:
Bits (1:31) = Device le number
Bit (0:1) = 1 Output spoolle
Bit (0:1) = 0 Input spoolle
79
I16
File's pending disposition
0 = No change, the disposition is the same as before the le was opened
1 = Permanent
2 = Temporary (tape les rewound)
3 = Temporary (same as 2 except tape les not rewound)
4 = Released (purged)
5 = Temporary (but the le was previously a permanent le)
4-138
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
80
CA
HFS syntax lename.
This itemnum returns a null-terminated POSIX-syntax system absolute
pathname for the le or directory referenced by lenum . On input the rst four
bytes of this buer are interpreted as a 32-bit unsigned integer specifying the
maximum buer size in bytes. This maximum buer size does not include the
four bytes used to represent this size. On output the rst four bytes of the buer
represent the pathname length excluding the null-terminator as an unsigned
integer. The pathname is returned in the bytes following the pathname length.
Bytes beyond the null-terminator should be considered undened. If the
maximum buer length is incorrect on input, variables allocated near the buer
may be overwritten or a bounds violation may occur. A zero pathname length is
returned for unnamed new les and when an error occurs. Zero is the mininum
buer length on input for this itemnum .
Format of the buffer on input:
byte
#1
#2
#3
#4 | #1
...
#N
+----+----+----+----+----+ ... +----+
|
maximum
|
|
|
length = N
|
|
+----+----+----+----+----+ ... +----+
Format of the buffer on output:
byte
#1
#2
#3
#4 | #1
...
#L
...
+----+----+----+----+----+ ... +----+ ...
|
length =
| / |
| \0 |
|
(L - 1)
|
|
|
|
+----+----+----+----+----+ ... +----+ ...
81
U32
The current number of hard links to the le.
82
I32
Time of last le access in clock format. The bit assignments are:
Bits 0 to 7
hours
Bits 8 to 15
minutes
Bits 16 to 23
seconds
Bits 24 to 31
tenths of seconds
#N
+----+
|
|
|
|
+----+
83
I32
Time of last le status change in clock format (See item 82 for a description of
clock format).
84
U16
Date of last le status change in calendar format. The bit assignements are:
Bits 0 - 7
Year of the century
Bits 8 - 15
Day of the year
Command Definitions
4-139
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
85
CA
File Owner
The full le owner name. Unused characters are blank lled. A symbolic zero
(ASCII 48 in decimal) is returned as the le owner for root directories, accounts,
and MPE groups created prior to the POSIX release.
86
I32
File owner identier
The le owner identier (UID). Zero is returned as the le owner ID for root
directories, accounts, and MPE groups created prior to the POSIX release.
87
CA
File group
The le group name. Unused characters are blank lled. A symbolic zero (ASCII
48 in decimal) is returned as the le group for root directories whose GID's have
not been assigned.
4-140
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
88
I32
File group identier
The le group identier (GID). Zero is returned as the le group ID for root
directories whose GID's have not been assigned.
89
U32
File type
The following valid le types may be returned:
0
Ordinary File
1
KSAM/3000
2
RIO
3
KSAM XL
4
CIR
5
Native Mode Spool File
6
MSG
7
Not Applicable
8
Compatability mode le
9
Directory
10-11
Not Applicable
12
Pipe
13
FIFO
14
Symbolic link
15
Device link
Command Definitions
4-141
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
90
U32
Record type
The following valid record types may be returned:
0
Fixed
1
Variable
2
Undened
3
Spool block
4
Root directory
5
Not applicable
6
Account directory
7
Group directory
8
Not applicable
9
Byte stream
10
Hierarchical directory
This item will return information based upon the record format that is logically
assoicated with the specied le designator and will not necessarily be the same
as the physical record structure of the le. It is possible with the HPFOPEN
intrinsic item 77, Read Format option, to access a le in a dierent mode than
the physical record type. For example, byte stream record les, when opened by
default, present variable record instead of the physical byte stream storage, since
the le was opened to behave like a variable record le. In order to determine the
true physical record structure of a le, use the FFILEINFO item 101.
91
I64
The current le size in bytes.
The value returned represents the current position of the End-of-File (EOF) and
may not reect the number of bytes actually occupied by the le on disk if the
le is sparsely allocated.
92
I32
KSAM XL le version:
This item returns a value indicating the version of a KSAM XL le. A value of 1
indicates an original type KSAM XL le, and a value of 2 indicates the next
generation KSAM XL le. A value of zero is returned if the le is not a KSAM
XL le.
93
U32
NM Plabel:
This item returns a 32-bit NM Plabel of a message le interrupt handler.
Interrupts may be enabled on message les by calling the FCONTROL intrinsic with
item 48 and the Plabel address.
4-142
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
94
I32
MPE/iX device type:
This item returns the following values for the following types of devices:
95
I32
0
Disk device
1
Tape device
2
Terminal device
3
Printer device
4
Remote device
5
Ports device
6
Reserved
7
Streams device
8
Sockets device
Close-on-Exec
This item returns a value indication whether or not this lenum is closed if one
the POSIX.1 exec() family of functions if called. A value of 1 means that the le
is closed on an exec() call, while a value of 0 indicates the le will survive across
exec() calls.
96
I32
POSIX Append mode
This item returns a value indicating whether or not this lenum has the POSIX.1
append mode ag set. When the append mode ag is set on les that support
this feature, all writes occur at the end of the le, although reads may occur
anywhere in the le. A value of 1 indicates that the POSIX.1 append mode is on,
while a value of 0 indicates the append mode is o.
The only time that the POSIX.1 append mode is valid is when a le has been
oepned for byte stream access (HPFOPEN option 77 with a value of 2).
97
I32
POSIX non-block mode
This item returns a value indicating whether or not this lenum has the POSIX.1
non-block ag set. When the non-block ag is set, on les that support this
feature, reads, writes, and opens can be aected in a le dependent manner. In
general, operations that would otherwise have impeded the caller results in
immediate return when this ag is set. A value of 1 indicates the non-block ag
is set, while a value of zero indicates the ag is not set.
The only time the non-block ag is valid is for pipes and FIFO's.
98
I32
Carriage Control
This item returns a value indicating whether or not the carriage control option is
in eect for this le. If carriage control is on, a value of 1 is returned. Otherwise,
a value of 0 is returned.
Command Definitions
4-143
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
99
I32
Setuid Flag
This item returns a value indicating whether or not this le has the setuid ag
turned on. When the setuid ag is on for a program le, the program will
execute under the user who owns the le rather than under the user who invoked
the program. A value of 1 indicates that the setuid ag is on; a value of 0
indicates the ag is o.
100
I32
Setgid Flag
This item returns a value indicating whether or not the le has the setgid ag
turned on. When the setgid ag is on for a program le, the program will execute
with the GID membership of the le rather than the GID membership of the
process that invoked the program. A value of 1 indicates that the setgid ag is
on; a value of 0 indicates that the ag is o.
101
I32
Physical record type
This item returns the record type of the le's physical record layout. It is
possible through the HPFOPEN option 77, Read Format option, to emulate a
dierent record structure than the actual physical record structure of the le. To
get the current logical record view, use FFILEINFO item 90.
The following values will be returned by this item:
102
I32
0
xed
1
variable
2
undened
3
spool block
4
root directory
5
not applicable
6
account directory
7
group directory
8
not applicable
9
byte stream
10
hierarchical directory
Dissallow le equation ag
This item returns a value indicating whether or not le equations were disallowed
when the le was opened. A value of zero indicates that le equations were
allowed; a value of 1 indicates le equations were disallowed. This item is
identical to bit 5:1 of the foptions.
4-144
Command Definitions
FFILEINFO
Table 4-6. FFILEINFO Itemnum/Item Values (continued)
Item Description
Itemnum Item
Type
103
I32
MPE Tape labels ag
This item returns a value indicating whether or not a tape was opened labeled or
unlabeled. A value of 0 indicates an unlabeled tape; a value of 1 indicates a
labeled tape. This item is identical to bit 6:1 of the foptions.
104
I32
File designator type
This item returns the le designator type for this le. It is identical to bit 10:3 of
the foptions. The following values can be returned by this item:
105
I32
0
A normal le open
1
$STDLIST
2
$NEWPASS
3
$OLDPASS
4
$STDIN
5
$STDINX
6
$NULL
7
$STDERR
ASCII/Binary ag
This item returns the setting of the le's ASCII/Binary ag. A value of 0
indicates that this is a binary le; a value of 1 indicates that this is an ASCII le.
This item is identical to bit 13:1 of the foptions.
106
I32
File domain
This item returns the domain in which the le currently resides. It is identical to
bit 14:2 of the foptions, and can return the following values:
0
New le domain
1
Permanent le domain
2
Temporary le domain
Command Definitions
4-145
FFILEINFO
Table 4-7. FFILEINFO File Codes
Integer
Mnemonic
0
4-146
Description
Default (unreserved)
1024
USL
User subprogram library
1025
BASD
Basic data
1026
BASP
Basic program
1027
BASFP
Basic fast program
1028
RL
Compatibility mode relocatable library
1029
PROG
Compatibility mode program le
1030
NMPRG
Native mode program le
1031
SL
Segmented library
1032
NMSL
Native mode executable library
1033
NMRL
Native mode relocatable library
1035
VFORM
VPLUS forms le
1036
VFAST
VPLUS fast forms le
1037
VREF
VPLUS reformat le
1040
XLSAV
Cross loader ASCII le (SAVE)
1041
XLBIN
Cross loader relocated binary le
1042
XLDSP
Cross loader ASCII le (DISPLAY)
1050
EDITQ
Edit quick le
1051
EDTCQ
Edit KEEPQ le (COBOL)
1052
EDTCT
Edit TEXT le (COBOL)
1054
TDPDT
TDP diary le
1055
TDPQM
TDP proof marked QMARKED
1056
TDPP
TDP proof marked non-COBOL le
1057
TDPCP
TDP proof marked COBOL le
1058
TDPQ
TDP work le
1059
TDPXQ
TDP work le (COBOL)
1060
RJEPN
RJE punch le
1070
QPROC
QUERY procedure le
1080
KSAMK
KSAM key le
1083
GRAPH
GRAPH specication le
1084
SD
Self-describing le
1090
LOG
User logging log le
Command Definitions
FFILEINFO
Table 4-7. FFILEINFO File Codes (continued)
Integer
Mnemonic
Description
1100
WDOC
Hewlett-Packard WORD document
1101
WDICT
Hewlett-Packard WORD hyphenation dictionary
1102
WCONF
Hewlett-Packard WORD conguration le
1103
W2601
Hewlett-Packard WORD attended printer environment
1110
PCELL
IFS 3000/XL character cell le
1111
PFORM
IFS 3000/XL form le
1112
PENV
IFS 3000/XL environment le
1113
PCCMP
IFS 3000/XL compiled character cell le
1114
RASTR
Graphics image in RASTR format
1130
OPTLF
OPT/3000 log le
1131
TEPES
TEPE/3000 script le
1132
TEPEL
TEPE/3000 log le
1133
SAMPL
APS/3000 log le
1139
MPEDL
MPEDCP/DRP log le
1140
TSR
Hewlett-Packard Toolset root le
1141
TSD
Hewlett-Packard Toolset data le
1145
DRAW
Drawing le for Hewlett-Packard DRAW
1146
FIG
Figure le for Hewlett-Packard DRAW
1147
FONT
Reserved
1148
COLOR
Reserved
1149
D48
Reserved
1152
SLATE
Compressed SLATE le
1153
SLATW
Expanded SLATE work le
1156
DSTOR
RAPID/3000 DICTDBU utility store le
1157
TCODE
Code le for TRANSACT/XL compiler
1158
RCODE
Code le for Report/3000 compiler
1159
ICODE
Code le for Inform/3000 compiler
1166
MDIST
Hewlett-Packard Desk distribution list
1167
MTEXT
Hewlett-Packard Desk text
1168
MARPA
ARPA messages le
Command Definitions
4-147
FFILEINFO
Table 4-7. FFILEINFO File Codes (continued)
Integer
4-148
Mnemonic
Description
1169
MARPD
ARPA distribution list
1170
MCMND
Hewlett-Packard Desk abbreviated commands le
1171
MFRTM
Hewlett-Packard Desk diary free time list
1172
None
Reserved
1173
MEFT
Hewlett-Packard Desk external le transfer messages le
1174
MCRPT
Hewlett-Packard Desk encrypted item
1175
MSERL
Hewlett-Packard Desk serialized (composite) item
1176
VCSF
Reserved
1177
TTYPE
Terminal type le
1178
TVFC
Terminal vertical format control le
1192
NCONF
Network conguration le
1193
NTRAC
Network trace le
1194
NLOG
Network log le
1195
MIDAS
Reserved
1211
ANODE
Reserved
1212
INODE
Reserved
1213
INVRT
Reserved
1214
EXCEP
Reserved
1215
TAXON
Reserved
1216
QUERF
Reserved
1217
DOCDR
Reserved
1226
VC
VC le
1227
DIF
DIF le
1228
LANGD
Language denition le
1229
CHARD
Character set denition le
1230
MGCAT
Formatted application le
1236
BMAP
Base map specication le
Command Definitions
FFILEINFO
Table 4-7. FFILEINFO File Codes (continued)
Integer
Mnemonic
Description
1242
BDATA
BASIC data le
1243
BFORM
BASIC eld order le for VPLUS
1244
BSAVE
BASIC saved program le
1245
BCNFG
Conguration le for default option BASIC program
1258
PFSTA
Pathow static le
1259
PFDYN
Pathow dynamic le
1270
RFDCA
Revisable form DCA data stream
1271
FFDCA
Final form DCA data stream
1272
DIU
Document interchange unit le
1273
PDOC
Hewlett-Packard WORD/150 document
1401
CWPTX
Reserved
1421
MAP
Hewlett-Packard MAP/3000 map specication le
1422
GAL
Reserved
1425
TTX
Reserved
1461
NMOBJ
Native mode object le
1462
PASLB
Pascal/XL source library
Figure 4-3. Foption Bit Summary
Command Definitions
4-149
FFILEINFO
Figure 4-4. Aoption Bit Summary
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. Access or calling sequence error.
Related Information
Intrinsics
Commands
Manuals
4-150
None
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
FFINDBYKEY
FFINDBYKEY
NM and CM callable.
Positions the record pointer at the beginning of the rst record matching the key value
comparison.
Note
For KSAM les only.
Syntax
I16V
CA
I16V
I16V
I16V
FFINDBYKEY( lenum,value,location,length,relop);
Parameters
lenum
16-bit integer by value (required)
value
Identies the le number of the le to be positioned.
character array (required)
location
Contains a value that determines which record is read. This value is
compared to the data contained in location in relation to the operator
specied in relop.
16-bit integer by value (required)
length
Species the relative byte location in the record of the key being used. Bytes
are numbered starting with 1. If location=0, the primary key is used.
16-bit integer by value (required)
Species the length of the key in bytes. If length=0, then the entire key is
used. If length is less than the full key length (generic key), then only the
length specied is used in the comparison with relop. The length parameter
must be equal to or less than the full length of the key when the le was
created. For numeric display keys or packed decimal keys, the full key length
must be used.
Command Definitions
4-151
FFINDBYKEY
relop
16-bit signed integer by value (required)
Species the relational operator for the comparison of the key value of the le
to the value specied in value. The record where the le is positioned has
this relation to key value:
Value
0
1
2
Meaning
Equal
Greater than
Equal to or greater than
When relop is set to 1 or 2, the search is for an approximate key.
Operation Notes
Split stack calls are permitted.
Can be used prior to a call to FREADC to position the chronological pointer to the record
located by the specied key.
To locate and read a single record, use the FREADBYKEY intrinsic.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The requested position was beyond the logical end-of-le or
beginning-of-le.
Request denied. An error occurred: an I/O error occurred, the relop
parameter could not be satised, a length less than the full length was
specied for a key with numeric display or packed decimal format, or a key
was not found when relop=0.
Related Information
Intrinsics
Commands
Manuals
4-152
FREADBYKEY
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
FFINDN
FFINDN
NM and CM callable.
Positions the logical record pointer to the relative record number according to the key
sequence.
Note
For KSAM les only.
Syntax
I16V
DV
I16V
FFINDN(lenum,number,location);
Parameters
lenum
16-bit signed integer (required)
number
Passes the le number of the le to be positioned.
double by value (required)
location
Species a record number relative to the rst logical record in the le. Record
numbers start with zero or one depending on the record numbering scheme
specied at le creation. The lowest numbered record applies to the record
with the lowest value in the specied key eld. A negative record number
positions the le pointer to the record with the smallest key value.
16-bit signed integer by value (required)
Passes the relative byte location in the record of the key to be used. The rst
byte of the record is considered 1. If location=0, the primary key is used.
Operation Notes
Split stack calls are permitted.
When the relative record number is specied, be sure not to confuse this number with the
chronological record number (the number of the record as it is stored in the le). The relative
record number is based on the value of a specied key, not its location in a le.
(KSAM/3000) If FFINDN is used to position the pointer before calling another procedure that
reads or updates the le in a shared environment, FLOCK must be called before calling FFINDN.
After performing the read or update operation, unlock the le. If the le is locked after calling
FFINDN, another user can change the pointer position without your program being aware of it.
Command Definitions
4-153
FFINDN
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The requested position was beyond the logical end-of-le.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
4-154
None
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
FGETINFO
FGETINFO
NM and CM callable.
Returns access and status information about a le.
Note
FGETINFO is provided for compatibility with MPE V/E-based systems only. It
is recommended that FFILEINFO be used to access data.
Syntax
I16V
CA
U16
U16
FGETINFO(lenum,formaldesig,foption,aoption
I16
I16
U16
U16 I16
lrecsize,devtype,ldevnum,hdaddr,lecode,
I32 I32 I32
I32
U16
I16
I32
I16
lrecptr,eof,lelimit,logcount,physcount,blksize,
I16
CA
I32
extsize,numextent,userlabels,creatorid,labaddr);
Parameters
lenum
16-bit signed integer by value (required)
formaldesig
Passes the le number of the le for which information is requested.
character array (optional)
Returns the actual designator of the le being referenced, in the following
format:
lename.groupname.accountname
The formaldesig array must be at least 28 bytes in length. When the actual
designator is returned, unused bytes in the array are lled with blanks on the
right. A nameless le returns an empty string.
The fully qualied name of the le referenced by lenum is returned as the
value of this parameter. Only names which can be expressed using MPE-only
semantics are returned. If the name of the object referenced by lenum
can not be expressed using MPE-name semantics, a CCL condition code is
returned. Calling FCHECK after this error will return FSERR391.
Command Definitions
4-155
FGETINFO
foption
16-bit unsigned integer by reference (optional)
Returns seven le access characteristics by setting bit groupings (refer to
Figure 4-5) as follows:
Bits
14:2
Value/Meaning
Domain:
The le domain searched to locate the le:
00
01
10
11
New le
Old permanent le
Old temporary le
Old temporary or permanent le
The record format extension bit is returned as the foption (1:1)
bit. Byte stream record format is represented as a record
format extension of one witha variable record format (foption
(8:2) bits equal to 01.
Directories, symbolic links, device links, pipes and FIFO's
cannot be represented by foptions . If the object referenced by
lenum
13:1
(ASC) Not valid for asynchronous device les; however, these
bits may have been set if le redirection was anticipated.
ASCII/Binary:
10:3
0
Binary
1
ASCII
Default le designator:
000
001
010
011
100
101
110
4-156
Command Definitions
Actual le designator (same as formal le designator)
Actual le designator $STDLIST
Actual le designator $NEWPASS
Actual le designator $OLDPASS
Actual le designator $STDIN
Actual le designator $STDINX
Actual le designator $NULL
FGETINFO
Bits
8:2
Value/Meaning
Record format foption :
00
01
10
11
Fixed-length records
Variable-length records
Undened-length records
Spoolle format records
7:1
(ASC) Not valid for asynchronous device les; however,
\xed-length" may have been set if le redirection was
anticipated.
Carriage control:
6:1
0
No carriage-control character expected
1
Carriage-control character expected
MPE/iX tape label:
0
1
5:1
Nonlabeled tape
Labeled tape
(ASC) Not valid for asynchronous device les. May have been
set if le redirection was anticipated.
Disallow FILE equation foption :
This option ignores any corresponding FILE command, so the
specications in the call to FOPEN/HPFOPEN take eect (unless
overridden by those in the le label). The following bit settings
apply:
1
0
Disallow FILE command
Allow FILE command
Command Definitions
4-157
FGETINFO
Bits
Value/Meaning
2:3
File type:
000
001
010
011
100
101
110
aoption
Standard le (STD)
KSAM/3000 le
Relative I/O le (RIO)
KSAM XL le
Circular le (CIR)
NM spoolle
Message le (MSG)
1:1
(ASC) Set to 000 for asynchronous device les.
Record format extension:
0:1
0
Do not use extended record format
1
Use extended record format
Reserved for the operating system
16-bit unsigned integer by reference (optional)
Returns le access information by setting bit groupings (see Figure 4-6), in
the following manner:
Bits
12:4
Value/Meaning
Access type aoption :
The type of access allowed users of this le:
11:1
0000 Read only
0001 Write only
0010 Write only (previous data not deleted)
0011 Append only
0100 Read/Write
0101 Update
0110 Execute
0111 Execute-Read
1000 Reserved
1001 Directory read access
Multirecord:
10:1
0
Nonmultirecord mode
1
Multirecord mode
Dynamic locking:
8:2
0
Disallow dynamic locking/unlocking
1
Allow dynamic locking/unlocking
Exclusive:
Species the access, from the time it is opened to the time it is
closed:
00
01
10
11
4-158
Command Definitions
Default
Exclusive access
Semi-Exclusive access
Shared access
FGETINFO
Bits
Value/Meaning
7:1
Inhibit buering:
Inhibits automatic buering by the operataing system and
allows I/O to take place directly between the stack and the
applicable hardware device:
0
1
5:2
Normal buering
Inhibit buering
(ASC) Not valid for asynchronous device les.
Multiaccess mode:
Provides the accessors with shared access to the le:
00
01
10
4:1
Nonmultiaccess
Intrajob multiaccess
Interjob multiaccess
(ASC) Not valid for asynchronous device les.
Nowait I/O:
Allows the accessors to initiate an I/O request and to have
control returned before completion of the I/O.
lrecsize
3:1
0
Nowait I/O not in eect
1
Nowait I/O in eect
File copy access:
0:3
0
Access in le's native mode
1
Access as standard sequential le
Reserved for the operating system.
16-bit signed integer by reference (optional)
Returns the logical record size associated with the le:
If the le was created as a binary le, this value is positive and expresses
the size in half words.
If the le was created as an ASCII le, this value is negative and expresses
the size in bytes.
For interprocess communication (IPC), when there is a call to FCONTROL with
controlcode =46 , the value returned in lrecsize is the size of the data records,
including the 4-byte header.
devtype
Maintained to ensure backward compatibility with MPE V/E-based systems.
MPE V/E record size limits are imposed when FGETINFO returns record size
information on all le types (STD, KSAM, RIO, CIR, MSG). If the record
size of the specied le exceeds MPE V/E limits, a zero is returned. Use
itemnum 67 of the FFILEINFO intrinsic or itemnum 30 of the FLABELINFO
intrinsic to obtain valid
MPE/iX record size data if the record size exceeds MPE V/E limits.
16-bit signed integer by reference (optional)
Command Definitions
4-159
FGETINFO
Returns the type and subtype of the device being used for a KSAM, RIO,
circular, or message le, or devices such as a tape drive, printer, or terminal
where bits (0:8) indicate device subtype, and bits (8:8) indicate device type.
For standard disk les, bits (8:8)=00000011 and bits (0:8)=00001000 (indicate
a 7933/35 disk drive).
ldevnum
If the le is not spooled or is opened as a spoolle through the logical device,
the returned devtype is actual. If an output le is spooled and was opened by
device class name, devtype contains the type and subtype of the rst device in
its class. (This may be dierent from the device actually used.)
16-bit unsigned integer by reference (optional)
hdaddr
Returns the logical device number (ldev) associated with the device where the
le label resides:
If the le is a disk le, ldevnum is the location of the le label. (File data
may reside on the same device as the le label.)
If the le is spooled, ldevnum is a virtual device number that does not
correspond to the system conguration I/O device list.
If the le is located on a remote computer, linked by a DS point-to-point
or X.25 link, the left eight bits (0:8) are the logical device number of the
distributed system (DS) device.
If the remote computer is linked by NS 3000/XL, the left eight bits (0:8) are
the remote environment of the connection. The right eight bits (8:8) are the
LDEV of the device on the remote computer where the le label resides.
If the DS device for the RFA or the LDEV is 0, then ldevnum returns a 0.
16-bit unsigned integer by reference (optional)
lecode
Returns 2048. Maintained to provide backward compatibility with MPE
V/E-based systems.
16-bit signed integer by reference (optional)
Returns the le code of a disk le.
lrecptr
(ASC) Not valid for asynchronous device les.
32-bit signed integer by reference (optional)
Returns the current logical record pointer setting. This value is the
displacement in logical records from record number 0 in the le and identies
the record that would be accessed next by an FREAD or FWRITE call.
eof
(ASC) Not valid for asynchronous device les.
32-bit signed integer by reference (optional)
Returns the pointer setting of the last logical record currently in the le
(equivalent to the number of logical records currently in the le). If the le
does not reside on disk, this value is zero. For interprocess communication
(IPC), when a call to FCONTROL with itemnum =46 is in eect, the number of
records returned in eof includes open, close, and data records.
(ASC) Not valid for asynchronous device les.
4-160
Command Definitions
FGETINFO
lelimit
32-bit signed integer by reference (optional)
Returns a number representing the last logical record that could exist in the
le (the physical limits of the le). If the le does not reside on disk, this
value is zero.
logcount
(ASC) Not valid for asynchronous device les.
32-bit signed integer by reference (optional)
physcount
Returns the total number of logical records passed to and from the program
during the current le access.
32-bit signed integer by reference (optional)
blksize
Returns the total number of physical I/O operations performed within the
process, against the le, since the last FOPEN/HPFOPEN call.
16-bit signed integer by reference (optional)
Returns the le block size:
If the le is binary, the value is positive and the size is in half words.
If the le is ASCII, the value is negative and the size is in bytes.
Maintained for backward compatibility with
MPE V/E-based systems. MPE V/E block size limits are imposed when
FGETINFO returns block size information on all le types (STD, KSAM, RIO,
CIR, MSG). If the block size of the specied le exceeds MPE V/E limits, 0
is returned. Use itemnum =68 of the FFILEINFO intrinsic or itemnum =31 of
the FLABELINFO intrinsic to get valid MPE/iX block size data if the block size
exceeds MPE V/E limits.
extsize
(ASC) Not valid for asynchronous device les.
16-bit unsigned integer by reference (optional)
Maintained to provide backward compatibility with MPE V/E-based systems.
numextent
(ASC) Not valid for asynchronous device les.
16-bit signed integer by reference (optional)
Maintained to provide backward compatibility with MPE V/E-based systems.
userlabels
(ASC) Not valid for asynchronous device les.
16-bit signed integer by reference (optional)
Returns the number of user labels dened for the le during creation. If the
le is not a disk le, this number is zero. When an old le is opened for
overwrite output, the value of userlabels is not reset, and old user labels are
not destroyed.
creatorid
(ASC) Not valid for asynchronous device les.
character array (optional)
An unqualied form of the le owner's name is returned as the value of this
parameter. The le owner is not necessarily the le's creator. File ownership
may be changed using the :ALTFILE command.
Command Definitions
4-161
FGETINFO
A symbolic zero (ASCII 48 in decimal) is returned as the le owner for root
directories, accounts, and MPE groups created prior to the POSIX release.
If the le is not located in the account in which the le owner is a member, a
blank le owner name is returned.
labaddr
(ASC) Not valid for asynchronous device les.
32-bit signed integer by reference (optional)
Returns a zero. Maintained for backward compatibility with MPE V/E-based
systems.
(ASC) Not valid for asynchronous device les.
Figure 4-5. Foption Bit Summary
4-162
Command Definitions
FGETINFO
Figure 4-6. Aoption Bit Summary
Operation Notes
Returns access and status information about a le located on any device. The le must be
opened by the calling process at the time of the FGETINFO call.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
FFILEINFO, FOPEN
None
Getting System Information Programmer's Guide (32650-90018), Using KSAM
XL (32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
4-163
FGETKEYINFO
NM and CM callable.
Requests access and status information about a KSAM le.
For KSAM les only.
Note
Syntax
I16V
BA
BA
FGETKEYINFO( lenum,param,control)
Parameters
lenum
16-bit signed integer by value (required)
param
Passes the le number of the le about which information is requested.
byte array (required)
Returns information describing the key information for a KSAM le. The
length depends on the number of keys in the le. The le size is given as the
number of sectors.
For KSAM XL les, refer to the Using KSAM XL (32650-90168) for a
complete description of this parameter.
control
For KSAM/3000 les, refer to the KSAM/3000 Reference Manual
(30000-90079) for a complete description of this parameter.
byte array (required)
Passes 128-words of control information about the key le.
Operation Notes
When a KSAM le is opened, information can be requested about it using this intrinsic. The
returned param parameter provides static information dened for the keys at the time it was
created. The control parameter provides dynamic information about the use of the le from
the time it was created. It counts the number of times the le was referenced by intrinsics,
and the date and time it was created, closed, updated, or written to.
4-164
Command Definitions
FGETKEYINFO
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred; insucient space was declared for param
or control, an illegal le number was specied, or the DB register is not set
to the user stack.
Related Information
Intrinsics
Commands
Manuals
None
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
4-165
FINDJCW
NM and CM callable.
Searches the job control word table for a specied job control word (JCW) and returns its
value.
Syntax
CA
U16
I16
FINDJCW(jcwname,jcwvalue,jcwstatus);
Parameters
jcwname
character array (required)
jcwvalue
Passes the name of the job control word (JCW) to be found. This name
can contain up to 255 alphanumeric characters, starting with a letter and
delimited by a nonalphanumeric character, such as a blank.
16-bit unsigned integer by reference (required)
jcwstatus
Returns the value of jcwname, if jcwname is found. If jcwname is not
found, jcwvalue is unchanged.
16-bit signed integer by reference (required)
Returns the execution status of the intrinsic, as follows:
4-166
Value
Meaning
0
1
2
3
Successful
Command Definitions
Jcwname > 255 characters
Jcwname does not start with an alpha character
Jcwname not found
FINDJCW
Operation Notes
There are three types of JCWs in the system:
User-dened
System-dened
System-reserved
FINDJCW can return the value of any type of JCW. The system-reserved JCWs are:
HPDATE
HPDAY
HPHOUR
HPMINUTE
HPMONTH
HPYEAR
Related Information
Intrinsics
Commands
Manuals
GETJCW, PUTJCW, SETJCW
SETJCW, SHOWJCW
Interprocess Communication Programmer's Guide (32650-90019)
and Command Interpreter Access and Variables Programmer's Guide
(32650-90011)
Command Definitions
4-167
FINTEXIT
NM and CM callable.
Causes the return from your interrupt procedure.
Syntax
U16V
FINTEXIT(interruptstate);
Parameters
interruptstate 16-bit unsigned integer by value (optional)
Passes the state in which software interrupts should be left. Bit (15:1)
controls this as:
Value
1
0
Meaning
Enable software interrupts (Default)
Disable software interrupts
Operation Notes
Software interrupts are set on return, according to interruptstate . If interruptstate is omitted,
the software interrupts are enabled by default.
Related Information
Intrinsics
Commands
Manuals
4-168
None
None
Accessing Files Programmer's Guide (32650-90017) and Interprocess
Communication Programmer's Guide (32650-90019)
Command Definitions
FINTSTATE
FINTSTATE
NM and CM callable.
Enables/disables all software interrupts against the calling process.
Syntax
U16
U16V
oldstate:=FINTSTATE(interruptstate);
Functional Return
oldstate
16-bit unsigned integer (assigned functional return)
Returns the previous state (enabled or disabled) of the software interrupts.
Parameters
interruptstate
16-bit unsigned integer by value (required)
Passes a ag enabling/disabling software interrupts through bit (15:1):
Value
0
1
Meaning
Disable software interrupts
Enable software interrupts
Operation Notes
The software interrupt facility enables FREAD/FWRITE completion processing with an interrupt
procedure. A call to FREAD or FWRITE is necessary to initiate the I/O request. Both of these
intrinsics return to the process as soon as the request has been started. When the operation
completes, the program is interrupted and control goes to the chosen interrupt procedure.
This performs whatever processing is necessary and then resumes the original program.
Software interrupts are armed for a particular le by specifying the interrupt procedure's
plabel in an FCONTROL call with itemnum =48. If aoption (4:1) is set to 0, selecting
itemnum =48 resets it to 1. Use IOWAIT or IODONTWAIT if itemnum =48 is used.
Software interrupts are inhibited just before entering an interrupt procedure. This is done
to stop unwanted nesting of the interrupt procedures. Each interrupt procedure should call
FINTEXIT to reenable other interrupts just before it exits.
Software interrupts are automatically inhibited before a 4CTRL5Y trap procedure. The
trap procedure can allow software interrupts only by calling the FINTSTATE intrinsic. The
RESETCONTROL intrinsic restores the interrupt state of the process to its pre-4CTRL5Y value
(unless the trap procedure issues an FINTSTATE call; RESETCONTROL makes no change).
Command Definitions
4-169
FINTSTATE
The rst parameter of the software interrupt procedure is the le number of the le that
caused the interrupt.
It is necessary to issue a call to the IODONTWAIT intrinsic against the le in order to complete
the request. When reading, the buer parameter is ignored in the FREAD call. The data is
moved to the array specied by the buer parameter of IODONTWAIT.
An incomplete FREAD/FWRITE request can be aborted by issuing an FCONTROL call with an
itemnum of 43 (abort nowait I/O).
Limitations:
Only message (MSG) les allow software interrupts.
No more than one incomplete FREAD/FWRITE can be outstanding for a particular le.
The interrupt is held o while executing within the operating system, with the following
exceptions:
PAUSE allows the interrupt.
IOWAIT allows the interrupt if the lenum parameter is set to 0.
In these instances, the intrinsic is reinvoked after the interrupt procedure executes.
Do not use FINTSTATE with remote les.
Related Information
Intrinsics
Commands
Manuals
4-170
None
None
Accessing Files Programmer's Guide (32650-90017) and Interprocess
Communication Programmer's Guide (32650-90019)
Command Definitions
FLABELINFO
FLABELINFO
NM and CM callable.
Returns information from the le label of a disk le.
Syntax
CA
I16V
I16
FLABELINFO( formaldesig,mode,fserrorcode,
I16A
REC I16A
itemnum,item,itemerror);
Parameters
formaldesig
character array (required)
Passes a formal le designator interpreted according to MPE-escaped
semantics. The le name must be terminated by a nonalphanumeric character
other than a period (.), a slash (/), a hyphen (-), and an underscore ( ). The
le referred to by formaldesig can be either an MPE le (i.e., one that uses
MPE syntax), or it can be an HFS syntax name beginning with a dot or a
slash.
If formaldesig is an escaped pathname:
you cannot reference remote les
it cannot express a name equivalent to lename :envid
you cannot use the device parameter (device =node #) to specify the remote
location of a device
If formaldesig follows MPE syntax, the le name can include password, group,
and account specications. The le name can backreference a le equation
and optionally be preceded by an asterisk.
The le referred to by formaldesig may reside either in an MPE group or
in an HFS directory. For les located in HFS directories, traverse directory
entries (TD) access is required to all directories specied in formaldesig . If
there is no TD access, FLABELINFO fails and a le system error code (398) is
returned in the fserrorcode parameter.
If the le can be named using both MPE syntax and HFS syntax (for
example, FILEA.MYGROUP.MYACCT and /MYACCT/MYGROUP/FILEA), the le can
be either permanent or temporary. If a temporary and a permanent le have
the same name, FLABELINFO returns information about the temporary le
only.
Command Definitions
4-171
FLABELINFO
mode
16-bit signed integer by value (required)
Passes an option specifying the valid backreferencing to le equations for the
le.
Bits
Value/Meaning
0:11
Reserved for future use.
11:1
Symbolic Link Traversal
0
To traverse through symbolic links, if they
exist.
1
Do not traversing through symbolic links, if
they exist.
12:2
Caller Privilege Level
fserrorcode
Allows the caller to pretend to be less privileged. The
privilege level is passed in this eld.
14:2
File Equations
0
Use le equations if they exist.
1
A le equation must be used.
2
Do not use a le equation.
16-bit signed integer by reference (required)
Returns a value indicating whether an error or warning occurred when
FLABELINFO attempted to return requested information:
A value of zero indicates that no errors were encountered.
A positive value is a le system error code and indicates that an error was
encountered and no information was returned in item.
A -1 indicates that an item error or warning has occurred. Check the
itemerror parameter to determine which item(s) has an error/warning and
what it is.
4-172
Command Definitions
FLABELINFO
itemnum
16-bit signed integer array (required)
item
To indicate the end of the list, place a zero in the element following the last
itemnum.
record (required)
Species which item value is to be returned. (Refer to Table 4-8.)
Returns the value of the item specied in the corresponding itemnum . (Refer
to Table 4-8.)
itemerror
Itemnum/items are paired such that the n th eld of the item record
corresponds to the n th element of the itemnum array.
16-bit signed integer array (required)
Returns an error number corresponding to the items specied in the
itemnum array. The itemnum/item and itemerror parameters are paired
such that the nth element of the itemerror array corresponds to the nth
element of the itemnum array.
If a value in the itemerror array is negative, a warning exists for the
corresponding item. If the value is positive, an error was detected for the
corresponding item. The absolute value of each value is a le system error
number.
Command Definitions
4-173
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values
Itemnum Mnemonic
1
CA
Item Description
File name (8 bytes):
The le name component for the le referenced in formaldesig is returned as the
value. If the le name is not expressible using MPE-only semantics, a le system
error code (391) is returned in the associated itemerror .
2
CA
Group name (8 bytes):
The group name component for the le referenced in formaldesig is returned as
the value. If the group name is not expressible using MPE-only semantics, a le
system error code (391) is returned in the associated itemerror .
3
CA
Account name (8 bytes):
The account name component for the le referenced in formaldesig is returned as
the value. If the account name is not expressible using MPE-only semantics, a
le system error code (391) is returned in the associated itemerror .
4
CA
File creator name (8 bytes):
An unqualied form of the le owner's name is returned as the value. The le
owner is not necessarily the le's creator.
A symbolic zero (ASCII 48 in decimal) is returned as the le owner for root
directories, MPE accounts, and MPE groups created prior to release 4.5.
If the le is not located in the account where the le owner is a member, a blank
le owner name is returned. Use itemnum =43 to obtain the full le owner name.
5
U32
Security matrix for access:
Returns the le's security matrix. This value does not indicate the actual
security enforced for a le, since group and account security masks can also
restrict access. This eld is ignored if an ACD is active on a le.
6
U16
File creation date:
The date in CALENDAR intrinsic format. Either creator (C) or manager (AM if le
is within account, otherwise SM) access required.
Zero is returned as the creation date for root directories, MPE accounts, and
MPE groups created prior to release 4.5.
7
U16
Last access date:
The date in CALENDAR intrinsic format. May not be up-to-date when the le is
open.
Zero is returned as the last access date for root directories, MPE accounts, and
MPE groups created prior to release 4.5.
8
U16
Last modication date:
The date in CALENDAR intrinsic format. May not be up-to-date when the le is
open.
Zero is returned as the modication date for root directories, MPE accounts, and
MPE groups created prior to release 4.5.
4-174
Command Definitions
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
9
I16
File code of disk le
10
U16
Number of user labels written:
May not be up-to-date when the le is open.
11
U16
Number of user labels available:
May not be up-to-date when the le is open.
12
I32
Total number of logical records possible in the le:
Equivalent to the le limit measured in logical records.
13
U16
File options:
The record format extension bit is returned as the foption (1:1) bit. Byte stream
record format is represented as a record format extension of one with a variable
record format (foption (8:2) bits equal to 01).
Directories, symbolic links, device links, pipes and FIFO's cannot be represented
by foption . If the object referenced by filenum is is an object, MPE error 399 is
returned in the associated itemerror .
Refer to the foption gure.
14
I16
Record size:
Maintained for compatibility with MPE V/E-based systems. (If a zero is
returned, use itemnum 30 instead.)
15
I16
Block size:
Maintained for compatibility with MPE V/E-based systems. (If a zero is
returned, use itemnum 31 instead.)
16
I16
Maximum number of extents:
Maintained for compatibility with MPE V/E-based systems. (If a zero is
returned, use itemnum 32 instead.)
17
I16
Last extent size:
Indicates sectors. May not be up-to-date when the le is open.
18
I16
Extent size:
Indicates sectors. (If a zero is returned, use itemnum 32 instead.)
Command Definitions
4-175
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
19
U32
Item Description
Number of logical records in le:
Equivalent to EOF. May not be up-to-date when the le is open.
20
U32
File allocation time:
The time when le was last restored (in CLOCK intrinsic format).
Zero is returned as the le allocation time for root directories, MPE accounts,
and MPE groups created prior to release 4.5.
21
U16
File allocation date:
The date when the le was last restored (in CALENDAR intrinsic format).
Zero is returned as the le allocation date for root directories, MPE accounts,
and MPE groups created prior to release 4.5.
22
I32
Number of open/close records:
MSG les only. May not be up-to-date when the le is open.
23
CA
Device name (8 bytes)
24
U32
Last modication time:
The time when the le was last modied (in CALENDAR intrinsic format). May not
be up-to-date when the le is open.
25
CA
First user label (user label 0) (256 bytes):
May not be up-to-date when the le is open. For all but PM les, Manager
capabilitiy (AM if le is within account, otherwise SM) or read/write (R/W)
access required. For PM les, Manager capability is required; otherwise,
FLABELINFO fails with FSERR93 .
27
REC
Unique le identier (UFID) (20 bytes)
28
U32
Total number of bytes allowed in le:
Equivalent to the le limit measured in bytes. May not be up-to-date when the
le is open.
29
U32
Start of le oset:
Indicates the byte oset where user data starts.
30
U32
Record size (indicates bytes
31
U32
Block size (indicates bytes)
32
U32
Extent size (indicates bytes)
33
CA
File lockword (8 bytes):
Returned if you are the le creator, account manager, or system manager.
4-176
Command Definitions
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
34
CA
Item Description
Volume restriction (34 bytes):
The last two characters indicate the type of restriction, as follows:
0
1
2
35
CA
File is placed on the specied volume at creation
File can be placed on any volume containing the specied class at creation
File can be placed on any volume within the specied volume set at creation
(Default)
Volume set names (32 bytes):
No restrictions.
36
U32
Transaction management log set id (4 bytes)
No restrictions.
37
U16
Logical device number
38
REC
Terminated HFS-syntax system absolute pathname:
Upon input, the rst four bytes are interpreted as a 32-bit unsigned integer
specifying the maximum available buer size in bytes. This maximum available
buer size does not include the four bytes used to represent this size. Upon
output, the rst four bytes represent the pathname length excluding the null
terminator as a 32-bit unsigned integer. The pathname is returned in bytes
following the pathname length. Bytes beyond the pathname terminator are
undened. If the maximum available buer size is incorrect upon input, variables
allocated near the buer can be overwritten or a bounds violation could occur. A
zero pathname length is returned for unnamed new les and when an error
occurs. Zero is the minimum buer length upon input for this itemnum .
Format of the buffer on input:
byte
#1
#2
#3
#4 | #1
...
#N
+----+----+----+----+----+ ... +----+
|
maximum
|
|
|
length = N
|
|
+----+----+----+----+----+ ... +----+
Format of the buffer on output:
byte
#1
#2
#3
#4 | #1
...
#L
...
+----+----+----+----+----+ ... +----+ ...
|
length =
| / |
| \0 |
|
(L - 1)
|
|
|
|
+----+----+----+----+----+ ... +----+ ...
#N
+----+
|
|
|
|
+----+
Command Definitions
4-177
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
39
U32
The current number of hard links to the le
40
I32
Time of last le access (clock format):
The bit assignments are:
bits
bits
bits
bits
41
I32
0-7 = hours
8-15 = minutes
16-23 = seconds
24-31 = tenths of seconds
Time of last le status change (clock format):
The bit assignments are:
bits
bits
bits
bits
42
U16
0-7 = hours
8-15 = minutes
16-23 = seconds
24-31 = tenths of seconds
Date of the last le status change (calendar format):
The bit assignments are:
bits 0-7 = year of century
bits 8-15 = day of the year
43
CA
File owner (32 bytes):
The full le owner name. Unused characters are lled with blanks. A symbolic
zero (ASCII 48 in decimal) is returned as the le owner for root directories,
accounts, and MPE groups created prior to release 4.5.
44
I32
File owner identier:
The le owner identier (UID). Zero is returned as the le owner ID for root
directories, MPE accounts, and MPE groups created prior to release 4.5.
45
CA
File group (32 bytes):
The le group name. Unused characters are lled with blanks. A symbolic zero
(ASCII 48 in decimal) is returned as the group for root directories where GIDs
have not been explicitly assigned.
46
I32
File group identier:
The le group identier (GID). Zero is returned as the group ID for root
directories where GIDs have not been explicitly assigned.
4-178
Command Definitions
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
47
U32
Item Description
File type:
Following are valid le types that can be returned:
0 = Ordinary file
1 = KSAM/3000
2 = RIO
3 = KSAM XL
4 = CIR
5 = Native Mode Spool File
6 = MSG
7 = N/A
8 = N/A
9 = Directory
10-11= N/A
12 = Pipe
13 = FIFO
14 = Symbolic Link
15 = Device Link
48
U32
Record type:
Following are valid record types that can be returned:
0 = fixed
1 = variable
2 = undefined
3 = spool block
4 = root directory
5 = N/A
6 = account directory
7 = group directory
8 = N/A
9 = byte stream
10 = hierarchical directory
49
I64
Current le size (in bytes):
The value returned represents the current position of the end-of-le (EOF) and
may not reect the number of bytes actually occupied by the le on disk if the
le is sparsely allocated.
Command Definitions
4-179
FLABELINFO
Table 4-8. FLABELINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
50
I32
Item Description
KSAM XL File Version:
This item returns a value indicating the version number of a KSAM XL le. A
value of 1 indicates an original type KSAM XL le. A value of 2 indicates the
next generation KSAM XL le. A value of zero is returned if the le is not a
KSAM XL le.
51
I32
KSAM XL Parameters:
This item returns the ksamparam for KSAM XL les, which is an array that
species the characteristics for up to 16 keys for the le.
52
I32
MPE/iX Device Type:
This item returns the following values for the following types of devices:
0=Disk device
1=Tape device
2=Terminal device
3=Printer device
4=Remote device
5=Ports device
6=Reserved
7=Streams device
8=Sockets device
53
I16
Secure/Release:
This item returns a value indicating whether the le is currently secured or
released. A value of 1 indicates that the le is secured. A value of zero indicates
that the le is released.
54
I32
Setuid ag
This item returns a value indicating whether or not the setuid ag is on for the
specied le. When the setuid ag is on for a program le (the value is 1), the
program will execute under the identity of the le's owner rather than assuming
the identity of the process that invoked the program. A value of zero indicates
the ag is o.
55
I32
Setgid ag
This item returns a value indicating whether or not the setgid ag is on for the
specied le. When the setgid ag is on for a program le (the value is 1), the
program will execute with the GID membership of the le rather than assuming
the GID membership of the invoking process. A value of zero indicates that the
ag is o.
4-180
Command Definitions
FLABELINFO
Figure 4-7. Foption Bit Summary
Condition Codes
CCE (2)
CCG (0)
Request granted.
Not returned. UnCCL (1)nRequest denied. An error occurred. Refer to the
fserrorcode and itemerror parameters for more information.
Related Information
Intrinsics
Commands
Manuals
None
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
4-181
FLOCK
NM and CM callable.
Dynamically locks a le. If dynamically locking more than one RIN, multiple RIN (MR)
capability is required.
Syntax
I16V U16V
FLOCK(lenum,lockag);
Parameters
lenum
16-bit signed integer by value (required)
lockag
Passes the le number of the le whose global resource identication number
(RIN) is to be locked.
16-bit unsigned integer by value (required)
Specify either conditional or unconditional locking by setting bit (15:1) as
follows:
Value
0
1
Condition Codes
Meaning
Locking takes place only if the ock semaphore of the global
unique le descripter (gufd) is used to control access to the le.
If the RIN is locked, control returns immediately to the calling
process, with condition code CCG (0).
Locking takes place unconditionally. If the le cannot be
locked immediately, the calling process suspends until the le
can be locked.
The following condition codes are possible when lockag bit (15:1)=1:
CCE (2)
Request granted.
CCG (0)
Not returned.
CCL (1)
Request denied. This le was not opened with the dynamic locking aoption
bit (10:1) specied in the FOPEN/HPFOPEN intrinsic, or there was an attempt to
lock more than one RIN and the calling process does not have multiple RIN
(MR) capability.
4-182
Command Definitions
FLOCK
The following condition codes are possible when lockag bit (15:1)=0:
CCE (2)
Request granted.
CCG (0)
Request denied. The le was locked by another process.
CCL (1)
Request denied. This le was not opened with the dynamic locking aoption
bit (10:1) specied in the FOPEN/HPFOPEN intrinsic, or there was an attempt to
lock more than one RIN and the calling process does not have multiple RIN
(MR) capability.
Operation Notes
On MPE/iX when a le is created (opened as a new le) with dynamic locking only one
accessor (the creator) is allowed. A subsequent call to FLOCK against such a le (although
unnessary) will succeed because the dynamic locking bit is not set to zero. On MPE V, when
a new le is created with dynamic locking the the dynamic locking bit is set to zero. For this
reason, a subsequent call to FLOCK will fail on MPE V.
Accessors that have opened a le with the dynamic locking option enabled must access the le
through the FLOCK intrinsic to gain exclusive access to the le. Since the use of this intrinsic
is discretionary, however, all accessors must agree to use FLOCK when writing to a le to
guarantee exclusive access. File locking is advised, but is not mandated by MPE/iX.
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
4-183
FLUSHLOG
NM and CM callable.
Flushes the contents of the user logging memory buer to the user logging le. User logging
(LG) or system supervisor (OP) capability is required.
Syntax
I32
I16
FLUSHLOG(index,logstatus);
Parameters
index
32-bit signed integer by reference (required)
logstatus
Passes the access to the user logging system. This is the value returned in the
index parameter of the OPENLOG intrinsic.
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the
intrinsic call:
Value
0
4
7
9
12
14
15
Meaning
Successful
Incorrect index parameter passed
Illegal capability; user logging (LG) or system supervisor (OP)
capability required
Error occurred while writing
System is out of disk space, user logging cannot proceed
Invalid access
End-of-le encountered
Operation Notes
The FLUSHLOG intrinsic writes the contents of the user logging memory buer to the disk
destination le. This helps to preserve the contents of the memory buer in the event of a
system failure. This intrinsic does not write special records.
Related Information
Intrinsics
Commands
Manuals
4-184
None
None
User Logging Programmer's Guide (32650-90027)
Command Definitions
FMTCALENDAR
FMTCALENDAR
NM and CM callable.
Passes any calendar date, in the same format as the CALENDAR intrinsic, and returns it in the
following format:
FRI, JAN 27, 1989
Syntax
U16V
CA
FMTCALENDAR(date,formatdate);
Parameters
date
16-bit unsigned integer by value (required)
Passes the calendar date, in the same format as the CALENDAR intrinsic:
formatdate
Bits
Value/Meaning
7:9
0:7
Day of year
Year of century
character array (required)
Returns the formatted calendar date in a 17-character array. If the day of the
month is less than 10, a blank precedes it, for example,
FRI, JAN 6, 1989
Operation Notes
If invalid input values are supplied, the output values returned are unpredictable; an error
status is not returned.
Related Information
Intrinsics
Commands
Manuals
None
None
None
Command Definitions
4-185
FMTCLOCK
NM and CM callable.
Passes the time of day, in the same format as the CLOCK intrinsic, and returns it in the
following format:
12:39 AM
Syntax
I32V
CA
FMTCLOCK(time,formattime);
Parameters
time
32-bit signed integer by value (required)
Returns the time of day in the same format as the CLOCK intrinsic:
formattime
Bits
Value/Meaning
24:8
16:8
8:8
0:8
Tenths of seconds
Seconds
Minute of hour
Hour of day
character array (required)
Returns the formatted time of day in an 8-character array. If the hour is a
single digit (prior to 10:00), the array contains a leading blank as follows:
7:39 AM
Operation Notes
If invalid input values are supplied, the output values returned are unpredictable; an error
status is not returned.
Related Information
Intrinsics
Commands
Manuals
4-186
None
None
None
Command Definitions
FMTDATE
FMTDATE
NM and CM callable.
Passes in the calendar date and time of day, in the same format as the CALENDAR and CLOCK
intrinsics, and returns it in the following format:
FRI, JAN 27, 1989, 12:39 AM
Syntax
U16V I32V
CA
FMTDATE(date,time,datetime);
Parameters
date
16-bit unsigned integer by value (required)
Passes the date in the same format as the CALENDAR intrinsic:
time
Bits
Value/Meaning
7:9
0:7
Day of year
Year of century
32-bit signed integer by value (required)
Passes the time in the same format as the CLOCK intrinsic:
Bits
24:8
16:8
8:8
0:8
datetime
Value/Meaning
Tenths of seconds
Seconds
Minute of hour
Hour of day
character array (required)
Returns the formatted date and time in a 27-character array. If the day of the
month is less than 10 or the time is one digit (before 10:00), a blank precedes
it. For example,
FRI, JAN 6, 1989, 7:39 AM
Command Definitions
4-187
FMTDATE
Operation Notes
If invalid input values are supplied, the output values returned are unpredictable; an error
status is not returned.
Related Information
Intrinsics
Commands
Manuals
4-188
None
None
None
Command Definitions
FOPEN
FOPEN
NM and CM callable.
Establishes access to a le and denes the physical characteristics of the le prior to access.
Syntax
I16
CA
U16V U16V I16V
CA
lenum:=FOPEN(formaldesig,foption,aoption,recsize,device,
CA
I16V
I16V
I32V
I16V
I16V
I16V
formmsg,userlabels,blockfactor,numbuer
I16V
lesize,numextent,initialloc,lecode);
Functional Return
lenum
16-bit signed integer (assigned functional return)
Returns a unique le number identifying the opened le.
Parameters
formaldesig
character array (optional)
Passes a formal le designator interpreted according to MPE-escaped
semantics. The le name must be terminated by a nonalphanumeric character
other than a period (.), a slash (/), a hyphen (-), and an underscore ( ).
The le referred to by formaldesig can be either an MPE le (i.e., one that
uses MPE syntax) or it can follow HFS syntax. If formaldesig follows MPE
syntax, the le name can include password, group, and account specications.
The le name can backreference a le equation and optionally be preceded by
an asterisk. If formaldesig follows HFS syntax, the le name must start with
either a dot (.) or a slash (/).
The le referred to by formaldesig may reside either in an MPE group or
in an HFS directory. For les located in HFS directories, traverse directory
entries (TD) access is required to all directories specied in formaldesig . If
there is no TD access, FOPEN fails and a call to FCHECK with lenum set to 0
will return a system error code (398) in the fserrorcode parameter.
If formaldesig is an escaped pathname:
you cannot reference remote les
it cannot express a name equivalent to lename :envid
you cannot use the device parameter (device =node #) to specify the remote
location of a device
Command Definitions
4-189
FOPEN
If formaldesig is the name of a user-dened le, it can begin with an asterisk
(*). If formaldesig is the name of a system-dened le, it can begin with a
dollar sign ($). When creating a KSAM le, formaldesig must be a unique le
name, that is, one not currently existing in the permanent le directory.
The formal le designator can contain command interpreter variables and
expressions that are evaluated before formaldesig is parsed and validated.
As the default, FOPEN creates a nameless le that can be read or written to,
but not saved. (The domain option of a nameless le must specify a new le
unless it is a device le.)
foption
(ASC) This parameter is recommended for use with asynchronous device les
because of the exibility it provides.
16-bit unsigned integer by value (optional)
Species up to eight dierent le characteristics by setting corresponding bit
groupings:
Note
For old les, default conditions are specied in the le label.
Device characteristics may override some foption s.
Bits
14:2
Value/Meaning
Domain
Indicates which le domain is searched to locate a le. A
nameless disk le must always be a new le. A device le (such
as a tape or terminal) always resides in the system le domain
(permanent le directory). Always specify a device le as old
or permanent.
The following bit settings are valid:
00
The le is new. No search is necessary.
01
The le is a permanent le. The system le domain
(permanent le directory) is searched.
10
The le is a temporary le. The job le domain
(temporary le directory) is searched.
11
The le is an old (permanent or temporary) le. The job
le domain (temporary le directory) is searched. If not
found, the system le domain is searched.
Default: 00
4-190
Command Definitions
FOPEN
Bits
Value/Meaning
13:1
ASCII/binary
Indicates which code, ASCII or binary, a new le is in when
written to a device that supports both codes. For disk les,
this also aects padding (zeros for a binary le, blank
characters for an ASCII le) that can occur when you issue a
direct-write intrinsic call (FWRITEDIR) to a record that lies
beyond the current logical end-of-le indicator. By default,
magnetic tape and les are treated as ASCII les. This option
is applicable only at le creation.
The following bit settings are valid:
0
Binary le
1
ASCII le
(ASC) Not valid for asynchronous device les.
10:3
Default: 0
Designator
Passes a value indicating a special le opening. Any of the
following special les can be specied with the formaldesig
parameter. For example, a le name of $STDLIST opens
standard list.
The following bit settings are valid:
000 The actual le designator is the same as the formal le
designator.
001 The actual le designator is $STDLIST.
010 The actual le designator is $NEWPASS.
011 The actual le designator is $OLDPASS.
100 The actual le designator is $STDIN.
101 The actual le designator is $STDINX.
110 The actual le designator is $NULL.
Default: 000
For example, if you pass MYFILE in the formaldesig parameter,
then using the designator option to equate it with $STDIN is
equivalent to allowing the le equation FILE MYFILE=$STDIN.
Command Definitions
4-191
FOPEN
Bits
Value/Meaning
The designator option is not equated with the formaldesig
parameter if both of the following conditions are true:
The disallow le equation option foption bit (5:1) allows le
equations for this le opening.
An explicit or implicit FILE command equating the formal
le designator to a dierent actual le designator occurs in
the job/session.
8:2
A leading * in a formal le designator passed by the
formaldesig parameter overrides the disallow le equation
option setting.
Record format
Bit settings indicate internal record structure for a le. This
option is applicable only at le creation.
The following bit settings are valid:
00
Fixed-length records. The le contains logical records of
uniform length.
Fixed-length records are supported by disk and magnetic
tape devices only.
01
Variable-length records. The le contains logical records
of varying length. This format is restricted to records
that are written in sequential order. The size of each
record is recorded internally. The actual physical record
size is determined by multiplying the record size
(specied or default) plus one by the blocking factor, and
adding one word for the end-of-block indicator.
This format is the only valid combination with byte
stream (1) record format extension.
For new les, this option is not allowed when NOBUF is
specied. If NOBUF is specied, then reads/writes are
performed on the entire block, not just the record.
Variable-length records are supported by disk and
magnetic tape devices only.
4-192
Command Definitions
FOPEN
Bits
Value/Meaning
10
Undened-length records. The le contains records of
varying length that were not written as variable-length
les. By default, all les not on disk or magnetic tape are
treated as containing undened-length records. The le
system makes no assumption about the amount of data
that is useful. You must determine how much data is
required. For undened-length records, only the data
supplied is written, with no information about its length.
Undened-length records are supported by all devices.
7:1
Default: 00
Carriage control
Indicates whether or not a carriage control directive is supplied
in the calling sequence of each FWRITE call that writes records
onto the le. This option is applicable only at le creation.
The following bit settings are valid:
0
No carriage-control directive is expected.
1
Carriage-control directives are expected.
Default: 0
Carriage control is supplied only for ASCII les. This option
and the ASCII/binary option (foption bit (13:1)) are mutually
exclusive, and attempts to open new les with both binary and
carriage control directives result in an access violation.
A carriage-control character passed through the controlcode
parameter of FWRITE is acted upon for les that have
carriage-control specied in HPFOPEN/FOPEN. Embedded control
characters are treated as data for les specied no
carriage-control, and do not invoke spacing. Spacing action can
be specied on les specied with carriage-control either by
embedding the control in the record or by sending the control
code directly through the controlcode parameter of FWRITE.
Command Definitions
4-193
FOPEN
Bits
Value/Meaning
If a carriage-control character is sent to a le where the control
cannot be executed directly (for example, line-spacing
characters sent to a disk or tape le), the control character is
embedded as the rst byte of the record. If a carriage-control
character is sent to other types of les, the control is
transmitted to the driver.
Control codes %400 through %403 are remapped to %100
through %103, so that they t into one byte and thus can be
embedded. Records written to the line printer with control
codes %400 through %403 should contain only control
information. A record written with control codes %400
through %403 and no data (count=0, or embedded control and
count=1) does not cause physical I/O of any sort.
To compute record size, the le system assumes carriage-control
information to be part of the data record. Therefore, specifying
the carriage-control option adds one byte to the record size
when the le is originally created. For example, a specication
of REC=-132,1,F,ASCII;CCTL results in a recsize of 133 bytes.
6:1
In general, the entire record can be read (the size of which is
returned in itemnum =67 of the FFILEINFO intrinsic). However,
on writes to les where carriage-control characters are
specied, the data transferred is limited to recsize -1 unless a
control of 1 is passed, indicating that the data record is
prexed with embedded carriage-control characters.
Labeled tape
0
No labeled tapes
1
Labeled tapes
(ASC) Not valid for asynchronous device les, but may be set
if le direction is anticipated.
Default: 0
4-194
Command Definitions
FOPEN
Bits
Value/Meaning
5:1
Disallow le equation option
Indicates whether or not to allow le equations. A leading * in
a formal le designator can override the setting to disallow
FILE. The following bit settings are valid:
2:3
0
Allow FILE equations to override programmatic or
system-dened le specications.
1
Disallow FILE equations from overriding programmatic or
system-dened le specications.
Default: 0
File type option
Indicates internal record structure used to access records in a
le. If the le is old, this option is ignored. Specifying a
designator option (foption bits (10:3)) value other than zero
overrides this option. This option is applicable only at le
creation.
The following bit settings are valid:
000 Standard (STD) le
001 KSAM/3000 le
010 Relative I/O (RIO) le
011 KSAM XL le
100 Circular (CIR) le
101 NM spoolle
110 Message (MSG) le
1:1
Default: 000
Record format extension
Byte stream record format is specied by setting the record
format, foption (8:2), to variable-length records (01) and the
record format extension, foption (1:1), to byte stream record
format (1). Zero is the default value for this option. Using any
record format value other than variable-length records with the
record format extension results in an FSERR 49
(unimplemented function). Byte stream record format may
only be specied for standard disk les. Specifying byte stream
record format for any other type of le result in FSERR 49
error.
Command Definitions
4-195
FOPEN
Bits
Value/Meaning
1:1 cont'd Record format extension
Files created using byte stream record format are assigned le
attributes which override values specied by FOPEN parameters.
The le attributes are as follows:
Option
foption (13:1)
foption (7:1)
recsize
blockfactor
0:1
aoption
DescriptionnValue
n
ASCII/binary ASCII (1)
n
Carriage control NOCCTL (0)
n
Logical record size 1 Byte (-1)
n
Blockfactor 1 Record/block
Reserved for the operating system
16-bit unsigned integer by value (optional)
Species up to eight dierent le access options by setting corresponding bit
groupings:
Bits
12:4
Value/Meaning
Access type
Indicates the type of access intended for the le. This option
restricts/allows minimal use of le system intrinsics.
The following bit settings are valid:
0000 Allows read access only, if the le's security provisions
specify read access. FWRITE, FUPDATE, and FWRITEDIR
intrinsic calls cannot reference this le. The end-of-le
(EOF) is not changed; the record pointer starts at 0.
0001 Allows write access only, if the le's security provisions
allow write access. Any data written in the le prior to
the current FOPEN request is deleted. FREAD, FREADSEEK,
FUPDATE , and FREADDIR intrinsic calls cannot reference
this le. The EOF is set to 0; the record pointer starts at
0. On magnetic tape an EOF is written when the le is
closed even if no data is written.
0010 Allows write-save access only, if the le's security
provisions allow write access. Previous data in the le is
not deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR
intrinsic calls cannot reference this le. The EOF is not
changed; the record pointer starts at 0. Therefore, data is
overwritten if a call to FWRITE is made. The system
changes this value to append for message les.
4-196
Command Definitions
FOPEN
Bits
Value/Meaning
0011 Allows append access only if the le's security provisions
allow either append or write access. FREAD, FREADDIR,
FREADSEEK, FUPDATE, FSPACE, FPOINT, and FWRITEDIR
intrinsic calls cannot reference this le. Data written by
the FWRITE intrinsic is appended to the EOF, thereby
extending the EOF. When a le is opened for append
access, it is impossible to overwrite data in the le. For
disk les, the EOF is updated after each FWRITE call.
Therefore, data cannot be overwritten.
0100 Allows read/write (I/O) access only if the le's security
provisions allows both read and write access. If both read
and write access are not allowed, the access type specied
in the security provisions (either read or write) is allowed.
Any le intrinsic except FUPDATE can be called for this
le. The EOF is not changed; the record pointer starts at
0. This option is not valid for message les.
0101 Allows update access only if the le's security provisions
allows both read and write access. If both read and write
access are not allowed, the access type specied in the
security provisions (either read or write) is allowed. All
le intrinsics, including FUPDATE, can be called for this
le. The EOF is not changed; the record pointer starts at
0. This option is not valid for message les.
0110 Allows execute access only if the le's security provisions
allow execute access. This access allows read/write access
to any loaded le. The program must be running in PM
to specify execute access. This option is not valid for
message les.
1000 Reserved for the operating system.
1001 Allows directory read access. This access allows you to
open a directory and read its contents. Attempt to open
a le with this type of access will return an error.
Command Definitions
4-197
FOPEN
Bits
Value/Meaning
11:1
Multirecord
Indicates whether or not individual read or write requests are
conned to record boundaries.
The following bit settings are valid:
0
Nonmultirecord mode (NOMULTI)
1
Multirecord mode (MULTI)
Default: 0
If the number of half words or bytes to be transferred (specied
in the length parameter of the read or write request) exceeds
the size of the physical record that is referenced, the remaining
half words or bytes are taken from subsequent successive
records until the number specied by length has been
transferred. For message (MSG) les not accessed with the
copy mode option (aoption bit (3:1)) enabled, the le system
sets this option to zero. This option is available only if the
inhibit buering option (aoption bit (7:1)) is set to 1.
4-198
Command Definitions
FOPEN
Bits
Value/Meaning
10:1
Dynamic locking
Enables/disables le locking for the le. When this option is
specied, the FLOCK and FUNLOCK intrinsics can be used to
dynamically permit or restrict concurrent access to a disk le
by other processes at specied times.
The following bit settings are valid:
0
Disallow dynamic locking/unlocking
1
Allow dynamic locking/unlocking
Default: 0
The process can continue this temporary locking/unlocking
until it closes the le. If several accessors are sharing the le,
they must all specify, or not specify, this option. For example,
if a le is opened with the dynamic locking option enabled, and
a subsequent accessor tries to open the le with dynamic
locking disabled, the subsequent attempt to open fails.
Dynamic locking/unlocking is made possible through the
equivalent of a global resource identication number (RIN)
assigned to the le and temporarily acquired by FOPEN.
Cooperating accessors that have opened a le with the dynamic
locking option enabled must access the le using either the
FLOCK and FUNLOCK intrinsics to ensure exclusive use of the le.
These accessors are allowed concurrent access even when not
using FLOCK and FUNLOCK, but exclusiveness is not guaranteed.
Lock access is available to a process if it has lock, execute,
append, or write access to the le. This option is ignored for
les not residing on disk.
If this option is specied for a new le, the dynamic locking bit
is NOT changed to 0 as it is on MPE V systems. When a le is
new, there can be only one accessor so setting this bit really
makes no sense. When opening a directory, dynamic locking
must be set to 0 (disallowed).
(ASC) Not valid for asynchronous device les.
Command Definitions
4-199
FOPEN
Bits
Value/Meaning
8:2
Exclusive option
Indicates continuous exclusive access to this le, from open to
close. Use this option when performing a critical operation (for
example, updating the le).
The following bit settings are valid:
00
If access type option (aoption bits (12:4)) species read
only access, then read-share access takes eect.
Otherwise, exclusive access takes eect. Regardless of
which access option was selected, FFILEINFO reports zero.
01
Exclusive access. After the le is opened, any additional
HPFOPEN/FOPEN requests for this le are prohibited until
this process issues the FCLOSE request or terminates. If
any process is already accessing this le when an
HPFOPEN/FOPEN call is issued with exclusive access
specied, an error status is returned. If another
HPFOPEN/FOPEN call is issued for this le while exclusive
access is in eect, an error code is returned to the process
that issued the call. Request exclusive access only if the
lock access mode is allowed by the security provisions for
the le.
For message les, specifying this value indicates that
there can be only one writer and only one reader.
Exclusive access cannot be specied for directories.
4-200
Command Definitions
FOPEN
Bits
Value/Meaning
10
Read-share access (semi-exclusive access). After the le is
opened, concurrent write access to this le through
another HPFOPEN/FOPEN request is prohibited, whether
issued by this process or another process, until this
process issues the FCLOSE request or terminates. A
subsequent request for the read/write or update access
type option (aoption bits (12:4)) obtains read access.
However, other types of read access are allowed. If a
process already has write access to the le when this call
is issued, an error code is returned to the calling process.
If another HPFOPEN/FOPEN call that violates the read only
restriction is issued while read-share access is in eect,
that call fails and an error code is returned to the calling
process. Request read-share access only if the lock access
mode is allowed by the security provisions for the le.
For message les, this value species there can be
multiple writers, but only one reader.
11
Share access. After the le is opened, concurrent access
to this le by any process is permitted, in any access
mode, subject to other security provisions in eect.
For message les, this value species that there can be
multiple readers and multiple writers.
Default: 00
Command Definitions
4-201
FOPEN
Bits
Value/Meaning
7:1
Inhibit buering option
Enables/disables automatic buering by the operating system.
If NOBUF is specied, I/O is allowed directly between the data
area and the applicable hardware device.
The following bit settings are valid:
0
Allow normal buering (BUF)
1
Inhibit buering (NOBUF)
Default: 0
NOBUF access is for physical block transfer; not logical record
transfer. If NOBUF is specied with this option as well as a
variable-length record structure in record format option
(foption bits (8:2)) and the le does not have a variable-length
record format, then the format is changed internally to an
undened-length record format. Therefore, you are responsible
for buer management. When performing an FWRITE, the
variable structure must be set up.
NOBUF access assumes responsibility for blocking and
deblocking of records in the le. To be consistent with les
built using buered I/O, records should begin on half word
boundaries. When the information content of the record is less
than the dened record length, pad the record with blanks if
the le is ASCII, or with zeros if the le is binary.
The record size and block size for les with NOBUF specied
follow the same rules as those les that are created using
buering. The default blocking factor for a le created under
NOBUF is 1.
If a le is opened NOBUF without multirecord mode specied in
multirecord option (aoption bit (11:1)), a maximum of only
one block of data per read or write can be transferred.
4-202
Command Definitions
FOPEN
Bits
Value/Meaning
The end-of-le (EOF) marker, next record pointer, and record
transfer count are maintained in terms of logical records for all
les. The number of logical records aected by each transfer is
determined by the size of the transfer.
Transfers always begin on a block boundary. Those transfers
that do not transfer whole blocks leave the next record pointer
set to the rst record in the next block. The EOF marker
always points at the last record in the le.
For les opened NOBUF, the FREADDIR, FWRITEDIR , and FPOINT
intrinsics treat the recnum parameter as a block number.
Indicate non-RIO access to an RIO le by specifying the le
NOBUF. Use the physical block size from FFILEINFO to
determine the maximum transfer length.
For message les, the le system normally resets the inhibit
buering option bit to zero. However, a message le can be
opened with NOBUF if the copy mode option (aoption bit (3:1))
is set to 1; this determines whether access to the le is
record-by-record or by block.
If you are reading a message le with the copy mode option
enabled, the inhibit buering option has the following meaning:
0
Read by logical record
1
Read by physical block
If writing to a message le, open it NOBUF; if the copy mode
option is enabled, access the le block-by-block.
(ASC) Not valid for asynchronous device les.
Command Definitions
4-203
FOPEN
Bits
Value/Meaning
5:2
Multiaccess mode option
Indicates how the le's record pointer is to be shared. This
option is useful for sharing standard input devices where there
is some natural sequence of access to the le. This option
permits processes located in dierent jobs or sessions to open
the same le and share that le's record pointer.
The following bit settings are valid:
00
No MULTI access. A unique record pointer is created for
this access to the le.
For message les, the default value of bits (5:2) is 10 for
normal access, or is 00 for copy mode access.
01
Intrajob MULTI access only allowed. A record pointer is
shared with all other opened les of the same name in the
same job/session who opened the le with this option set
to either 01 or 10.
10
Interjob MULTI access allowed. A record pointer is
shared with all other opened les of the same name on
the system.
Default: 0
4:1
(ASC) Not valid for asynchronous device les.
Nowait I/O option
Enables/disables nowait I/O. Determines whether or not the
accessor has control returned before the completion of an I/O
request. The nowait I/O implies the inhibit buering option
(aoption bit (7:1)); if NOBUF is not specied, the le system
does it for you and multirecord access is not available. This
option is not available if the le is located on a remote
computer. When opening nonmessage les, the process must
be running in privileged mode to specify this option.
The following bit settings are valid:
0
Nowait I/O not in eect
1
Nowait I/O in eect
Default: 0
Nowait I/O cannot be specied for directories.
4-204
Command Definitions
FOPEN
Bits
Value/Meaning
3:1
Copy mode option
Determines whether a le should be treated as a standard
sequential le (copy by logical record) or physical block (copy
to another le). Copy must be set to obtain EXCLUSIVE
access. This causes the multiaccess bits to be set to 00. The
following values are valid:
0
The le is accessed as its own le type.
1
The le is treated as a standard (STD) le, with
variable-length records. For message les, this allows
nondestructive reading of an old message le at either the
logical record or physical-block-record level. Only
block-level access is permitted if the le has message le
format. This prevents incorrectly formatted data from
being written to the message le while it is unprotected.
In order to access a message le in copy mode, a process
must be able to obtain EXCLUSIVE access to the le. If
opening the message le for read only, the le system
tries to grant exclusive access; for write only access to the
message le, the EXCLUSIVE bits (8:2) in the aoptions
must be set to 01.
0:3
Default: 0
Reserved for the operating system.
Command Definitions
4-205
FOPEN
recsize
16-bit signed integer by value (optional)
Passes the size, in half words or bytes, of the logical records in the le. If
recsize =0, the system uses the default record size, 256 bytes. Positive values
are half words; negative values are bytes. The valid range is dependent on
storage and record formats:
For xed-length and undened-length ASCII les, the valid range is
1..32,767 bytes.
For variable-length ASCII les and xed-length, variable-length, and
undened-length binary les, the range is 1..32,766 bytes (1..16,383 half
words). All odd values specied are rounded up to the next even value (the
next half word boundary).
device
Default: Device dependent; refer to the Accessing Files Programmer's Guide
(32650-90017) for default record sizes.
character array (optional)
Passes a string of ASCII characters terminating with any nonalphanumeric
excluding a slash (/) or period (.), designating the device where the le is
to reside. This parameter optionally species density for tape les (;DEN=
parameter) and/or environment les for certain Hewlett-Packard laser printers
(;ENV= parameter), a remote environment (node# ), and whether the device is
to be allocated on a remote machine (;VTERM).
Remote environments (device =node #) cannot be specied for directories, byte
streams, or when the formal le designator species an escaped pathname.
Syntax of the options available through the device parameter are:
2
3
*
6 **vol
7
7
36
2
7
device= node# 6
6 *volclass 7
4 devname 5
devclass
2
2
2
4-206
;DEN=density
3
;ENV=printenv
;VTERM
Command Definitions
3
3
FOPEN
node # remote environment option
Passes a remote node name to be accessed through remote le access
(RFA). The node name string must be followed by a pound character
(#) to delimit the string. The internal format of the name must
match that dened by the NS 3000/XL subsystem. Refer to the NS
3000/XL User/Programmer Reference Manual (36920-90001).
Default: Local le access
*
volume set option
Passing only an asterisk character (* ) indicates to FOPEN that the
disk le can span all volumes in the volume set bound to the group
where the le resides. No set name is actually passed. This option is
applicable only at le creation.
**vol volume name option
Passing a name, preceded by two asterisks (** ), indicates that the
disk le is restricted to the volume whose name is specied in vol .
The specied volume must reside within the volume set bound to the
group where the le resides. This option is applicable only at le
creation.
*vol- volume class option
class Passing a name, preceded by one asterisk (* ), indicates that the
disk le is restricted to the volume class whose name is specied
in volclass . The specied volume class must reside within the
volume set bound to the group where the le resides. This option is
applicable only at le creation.
Command Definitions
4-207
FOPEN
devname
devclass
device name option
Passes the logical device number, in ASCII format, of a specic
device. The le is assumed to be permanent. If the logical device
number of a nonshareable device is specied, the nonshareable device
must be ready prior to the FOPEN call.
If the device name option is used to open a le residing on a disk,
specify the logical device number of the disk drive where a volume
which resides within the volume set bound to the group where the
le resides is mounted (applicable only at le creation). Thereafter,
the disk le is associated with that volume, not with the originally
specied logical device number.
device class option
Passes a device class name or volume class name of up to eight
alphanumeric characters beginning with an alpha character. For
example, TAPE or DISC. If devclass is specied, the le is allocated to
any available device in that class.
If the device class option is used to open a le residing on a disk,
specify a device class name that corresponds to a valid and mounted
volume class name; otherwise, it is assumed that the attempt is to
open a device le not a disk le. Applicable only at le creation. The
specied volume class must reside within the volume set bound to
the group where the le resides. The le is free to span any of the
volumes that fall within the specied volume class.
Note
If either volumeset, vol, volclass, devname , or devclass is not specied, FOPEN
defaults to a disk le located on the volume class DISC bound to the group
where the le resides. The le is free to span all volumes in the volume class
DISC.
When opening a magnetic tape that is shared for a second time, open the
device with the device name option instead of device class option. This
ensures that the system operator is not confused by a second tape request.
4-208
Command Definitions
FOPEN
tape density option
density Passes the tape density to be used while writing to a tape le. This
option is applicable only when writing to a tape on a drive that
supports more than one density. When reading from a tape, the
density of the tape overrides the density value specied.
To specify density when writing to the tape le, use the keyword
;DEN=.
Default: The highest density available on the device opened
;ENV= printer environment option
print- Passes the name of a le that contains a printer environment. Valid
env
only for specied printers. If opening an Hewlett-Packard 268x page
printer le, an optional printing environment can be specied for the
job. The printing environment is dened as all of the characteristics
of the printed page that are not part of the data itself, including
the page size, the margin width, the character set, the orientation
(horizontal or vertical), and the name of the forms to use. If an
environment le is not specied, the le system selects a default
printer environment.
To specify a printer environment, assign the keyword ;ENV=, followed
by the name of the environment le, to the device parameter in the
form ;ENV=printenv . Any environment selected remains active until
replaced by a new environment or a call FCLOSE to close the printer.
Default: No printer environment le specied
;DEN=
Command Definitions
4-209
FOPEN
;VTERM reverse VT option
Indicates that the specied device name is allocated on a remote
machine. Specify the remote location of a device with the device
parameter as VTERM. Specify the remote environment in the same
open request, using either the formaldesig parameter or the remote
environment option (see node# above) of the device parameter.
Reverse VT is almost the same as a terminal opened up through
remote le access, except that no session is required on the remote
machine.
formmsg
Default: No reverse VT
character array (optional)
Passes a forms message that can be used for sending messages (for example,
telling the system operator what type of paper to use in the line printer)
The message is a string of ASCII characters terminated by a period. The
maximum number of characters allowed is 49, including the terminating
period; more than 49 characters are truncated.
Used for tape label information if bit (6:1) of the foption parameter is set.
The tape label information is formatted as follows:
.[volid[,type[,exp[,seq]]]];
The period is required so that the tape label information is not mistaken for a
forms message.
volid Volume identier, consisting of <=6 printable characters. In a
multivolume set, specify only the rst volid .
type
Label type, identied by three alphabetic characters:
exp
4-210
ANS - ANSI standard labels (default)
IBM - IBM standard labels
Month/day/year of the le expiration date or the date when the
le information is no longer valid. The le can be overwritten after
this date. If the default is 00/00/00, the le can be overwritten
immediately. In a volume set, le expiration dates must be equal to
or earlier than the date on the previous le.
Command Definitions
FOPEN
seq
Use one of the following methods to specify the position of the le in
relation to other les on the tape:
A zero, which causes a search of all volumes until the le is found.
An unsigned integer (1-9999), which species the position of the le
relative to the current le on the tape.
ADDF which causes the tape to be positioned to add a new le on
the end of the volume (or last volume in a multivolume set).
NEXT which positions the tape at the next le on the tape. If this
is not the rst FOPEN for the le and a rewind occurred on the last
close, then the position remains at the beginning of the previous
le.
Default: NEXT
(KSAM) Contains a description of the primary key and up to 15
alternate keys:
If a new le is being created, this parameter must be specied.
If this is an existing le, check agword eld to see if the default
values are acceptable; if not acceptable, specify this eld explicitly.
For KSAM XL les, refer to the Using KSAM XL (32650-90168) for a
complete description of this parameter.
For KSAM/3000 les, refer to the KSAM/3000 Reference Manual
(30000-90079) for a complete description of this parameter.
Command Definitions
4-211
FOPEN
userla- 16-bit signed integer by value (optional)
bels
Passes the number, in the range 0..254, of user-label records to be
created for the le. Applicable to new disk les only.
Default: 0
(ASC) Not valid for asynchronous device les.
block- 16-bit signed integer by value (optional)
factor Passes the number of logical records in one physical record (block).
This value is used to calculate the physical record size for disk and
magnetic tape les. The valid range for this option is 1..255. If a
value greater than 255 is specied, FOPEN resets the value to 255. If
a value less than 1 is specied, FOPEN resets the value to the default
blockfactor setting.
For xed-length records, blockfactor species the actual number
of records in a block. For variable-length records, blockfactor
is interpreted as a multiplier used to compute the block size
(recsize*blockfactor ). For undened-length records, blockfactor is
always one logical record per block.
Default: For les opened BUF, the default is calculated by dividing
the specied recsize into the physical record size (block size)
congured for the device. For les opened NOBUF, the default is 1.
(ASC) Not valid for asynchronous device les.
4-212
Command Definitions
FOPEN
numbuer
16-bit signed integer by value (optional)
Passes the number of buers, number of copies, and output priority
indicated by setting the following bits:
Bits
11:5
Value/Meaning
Numbuers
Indicates the number of buers to allocate to the le. The
valid range is dependent on le type:
For standard les, the valid range is 1..31.
For circular and RIO les, the valid range is 1..16.
For message les, the valid range is 2..16 (if a 1 is specied,
the le system sets this option to 2 and no error is returned).
For KSAM/3000 les, the valid range is 1..20.
Not used for KSAM XL les.
This option is ignored for standard disk les, useful only for
slow devices (such as tapes) used in a buered mode, and is
not applicable for les representing interactive terminals.
This option must not specify a number of buers whose
combined size exceeds the physical capacity of the le.
4:7
Default: 00010 (decimal 2)
Spooler copies
Indicates the number of copies of the le to be produced by the
spooling facility. The valid range is 0 . . . 127. This option is
applicable to spooled devices only. Specify this option for a le
already opened (for example, $STDLIST ), this is the highest
value supplied before the last FCLOSE takes eect. The copies
do not appear continuously if the system operator intervenes or
if a le of higher output priority is ready before the last copy is
complete.
Default: 0000001 (decimal 1)
Command Definitions
4-213
FOPEN
Bits
Value/Meaning
0:4
Output priority
Indicate the output priority to be attached to the le for
spooled output. Applicable only to spooled devices. The valid
range for this option is the binary equivalent of 1..13. The
output priority must be a number between 1 (lowest priority)
and 13 (highest priority), inclusive. If a value less than the
current outfence set by the system operator is specied, le
printing is deferred until the operator raises the output priority
of the le or lowers the outfence. Specify this option for a le
already opened (for example, $STDLIST), the highest value
supplied before the last FCLOSE takes eect.
Default: 1000 (decimal 8)
lesize
32-bit signed integer by value (optional)
Passes the maximum le capacity. For variable-length records, the capacity is
expressed in blocks (block = recordsize * blockfactor ). For xed-length and
undened-length records, the capacity is expressed in logical records:
The maximum le size for standard and KSAM XL les is 4,294,901,759
bytes (4 gigabytes less 64K bytes).
The maximum le size for RIO, circular, and message les is dependent
upon both the record size and number of extents dened for the le:
For circular and RIO les, a maximum le size of 500 megabytes is
possible if recsize =256 bytes and numextent =32.
For message les, a maximum le size of 500 megabytes is possible if
recsize =128 bytes and numextent =32.
Applicable only at le creation.
Default: 1023 records
(ASC) Not valid for asynchronous device les.
4-214
Command Definitions
FOPEN
numextent
16-bit signed integer by value (optional)
Passes a value in the range 1..32 that determines the number of extents for
the le. If a value of 1 and an initialloc value of 1 is specied, the le is
created as one contiguous extent of disk space. If a value >1 is specied, a
variable number of extents (with varying extent sizes) is allocated on a need
basis. Applicable only at le creation.
Default:
initialloc
>8 extents
(ASC) Not valid for asynchronous device les.
16-bit signed integer by value (optional)
Passes an integer value in the range 1..32 that determines the number of
extents to be allocated to the le initially. Applicable only at le creation.
Default: 1
lecode
(ASC) Not valid for asynchronous device les.
16-bit signed integer by value (optional)
Passes a value that can be used as a le code to identify the type of le. This
code is recorded in the le label and is accessible through the FFILEINFO
intrinsic. Applicable only at le creation (except when opening an old le that
has a negative le code).
If the program is running in user mode, specify a le code in the range
0..32,767 to indicate the le type being created; programs running in user
mode can access les with non-negative le codes. If the program is running
in privileged mode, specify a le code in the range -32,768..32,767; programs
running in privileged mode can access les with a le code in the range
-32,768..32,767. If an old le with a negative le code is opened, the le code
specied must match the le code in the le label.
Negative le codes are only allowed for le in MPE groups.
Default: 0
(ASC) Not valid for asynchronous device les.
Command Definitions
4-215
FOPEN
Table 4-9. FOPEN/HPFOPEN Parameter Equivalents
FOPEN Parameter
HPFOPEN Itemnum,Item
lenum (functional return)
lenum (parameter)
formaldesig
2,formaldesig
foption :
Bits (14:2) Domain
Bit (13:1) ASCII/binary
Bits (10:3) File designator
Bits (8:2) Record format
Bit (7:1) Carriage-control
Bit (6:1) Labeled tape
Bit (5:1) Disallow le equation
Bits (2:3) File type
aoption:
Bits (12:4) Access type
Bit (11:1) Multirecord
Bit (10:1) Dynamic locking
Bits (8:2) Exclusive
Bit (7:1) Inhibit buering
Bits (5:2) Multiaccess mode
Bit (4:1) Nowait I/O
Bit (3:1) File copy
3, domain
53, ASCII/binary
5, le designator
6, record format
7, carriage-control
8, labeled tape
9, disallow le equation
10, le type
11, access type
15, multirecord
12, dynamic locking
13, exclusive
46, inhibit buering
14, multiaccess mode
16, nowait I/O
17, le copy
recsize
19, record size
device
20, device name
22, volume class
23, volume name
24, density
25, printer environment
26, remote environment
42, device class
48, reverse VT
formmsg
8, labeled tape label
28, spooled message
30, labeled tape type
31, labeled tape expiration
32, labeled tape sequence
54, KSAM parms
userlabels
33, user labels
blockfactor
40, block factor
4-216
Command Definitions
FOPEN
Table 4-9. FOPEN/HPFOPEN Parameter Equivalents (continued)
FOPEN Parameter
HPFOPEN Itemnum,Item
numbuers:
Bits (11:5) Numbuers
Bits (4:7) Spooler copies
Bits (0:4) Output priority
44, numbuers
34, spooler copies
27, output priority
lesize
35, lesize
numextent
47, numextent
initialloc
36, initial allocation
lecode
37, lecode
Operation Notes
A le can be referenced by its formal le designator. When executed, a unique le number is
returned to the process. This le number can be used, rather than the formal le designator,
in other calls to this le.
Note
If a le is opened with read access only (bits 12:4 = 0000) a subsequent call
to FOPEN to write and set eof to 0 (bits 12:4 = 0001) succeeds but only after
the system changes the call to write but not set eof to 0 (bits 12:4 =0010).
This protects the reader, who opened the le rst, from having the eof set to
0.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The le is open.
Not returned.
Request denied. For example, another process already has exclusive or
semi-exclusive access for this le, the privilege level of this le is not user (3),
or an initial allocation of disk space cannot be made due to lack of disk space.
If the le is not opened successfully, the le number value returned by FOPEN
is 0. Call the FCHECK intrinsic for more details.
Related Information
Intrinsics
Commands
Manuals
HPFOPEN
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
4-217
FPARSE
NM and CM callable.
Parses and validates le designators. Only MPE syntax names can be parsed. Escaped or
POSIX syntax names will return errors.
Syntax
CA
I16A U16A I32A
FPARSE(formaldesig,result,item,vector);
Parameters
formaldesig
character array (required)
Passes the le reference string to be parsed. Terminate the string with any
nonalphanumeric character except a slash (/), period (.), or colon (:).
result
If an error occurs, the rst element of the vector array returns the byte oset
of the invalid item in formaldesig.
16-bit signed integer array (required)
Returns two elements; the rst element is the error number, the second
element is reserved and always returns 0.
A positive value indicates the syntax of the specied le reference is correct
and what type of le reference is being made. A negative value indicates a
syntax error in the le reference.
The possible error number values are:
Value
0
1
2
Meaning
Regular le designator
Backreference (* is the rst character in formaldesig )
System le ($ is the rst character in formaldesig )
The default designator numbers for system les, as dened for
FOPEN foption , are:
0 File name
1 $STDLIST
2 $NEWPASS
3 $OLDPASS
4 $STDIN
5 $STDINX
6 $NULL
4-218
Command Definitions
FPARSE
Value
-1
-2
-3
-4
-5
-6
-7
-8
-9
-101
-102
-103
-104
-105
-106
-107
-108
-109
-110
-111
-112
-113
-114
-115
Note
Meaning
Invalid item values
Parameter bounds violation
Illegal delimiter; misuse of ., /, or :
Item specied without specifying vector
Illegal value in item
Item list not terminated by 0
Undened system le
Lockword not allowed in backreferenced (*) le
NS 3000/XL not present; envidname was specied
First character of the le name not alphabetic
File name expected in the string
File name identier too long
First character of lockword not alphabetic
Lockword expected in string
Lockword identier too long
First character of group name not alphabetic
Group name expected in string
Group name identier too long
First character of the account name not alphabetic
Account name expected in string
Account name identier too long
First character of envidname not alphabetic
Expected envidname in string
Identier for envidname too long
Up to three identiers can be specied, separated by a period (.), in an
envidname ; errors -113 through -115 can reference one of the three identiers.
The error pointer indicates the location.
If NS 3000/XL is not installed on the system, FPARSE returns a -9 for le
designators with an envidname after the le name. This error indicates
that everything up to envidname was valid, but a parsed vector array is not
returned.
items
16-bit unsigned integer array (optional)
Passes an item code, one value per element, indicating what the corresponding
vector parameter points to:
Command Definitions
4-219
FPARSE
Value
0
1
2
3
4
5
vector
Meaning
End of item list
File name
Lockword
Group name
Account name
NS 3000/XL envidname
32-bit signed integer array (optional)
Returns vectors, one per element, for the requested item .
A vector cannot be passed without a corresponding item value.
Note
Information is returned as follows:
Bits
Value/Meaning
16:16
Return the length of the string specied by the corresponding
items parameter.
0:16
If zero is returned, the requested item in formaldesig was not
specied.
Return the oset, in bytes, from the base of the formaldesig
parameter to the rst element of the string segment specied
by the corresponding item parameter.
The last element returns the le designator length passed in formaldesig
(bits (16:16)) and the default type (bits (0:16)) if the result parameter
indicates a system le.
It is not recommended that applications parse le names on their own.
Instead, use the FPARSE intrinsic to do so.
Note
Related Information
Intrinsics
Commands
Manuals
4-220
None
None
Accessing Files Programmer's Guide (32650-90017) and the NS 3000/XL
User/Programmer Reference Manual (36920-90001)
Command Definitions
FPOINT
FPOINT
NM and CM callable.
Sets the logical record pointer for a disk le containing xed-length or undened-length
records to any logical record. When the next FREAD or FWRITE le request is made, this record
is read or written to.
(KSAM) Sets both the chronological and logical record pointers to the next record in
chronological sequence (the order records were written to the le).
Syntax
I16V
I32V
FPOINT(lenum,lrecnum);
Parameters
lenum
16-bit signed integer by value (required)
lrecnum
Passes the le number of the le where the pointer is to be set.
32-bit signed integer by value (required)
Passes the relative logical record (or block number for a NOBUF le) where
the logical record pointer is to be positioned. The number of the rst logical
record is 0.
On disk les, the EOF indicator is the le limit.
If the lenum parameter refers to a byte stream le, the lrecnum parameter is
interpreted as a byte oset to which the le pointer is set.
(KSAM) For xed-length les, record numbering starts with 0 or 1, depending
on how the le was created.
(KSAM/3000) For KSAM/3000 les with variable-length records, the number
of the rst logical record is 0.
Command Definitions
4-221
FPOINT
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The logical record pointer position is unchanged. Positioning
was requested at a point beyond the le limit.
Request denied. The logical record pointer position is unchanged because of
one of the following:
Lrecnum <0
Invalid lenum parameter
I/O is pending on a nowait request
Spooled le
Not a direct access disk le
File does not contain xed-length or undened-length records
Not allowed with append access
(KSAM) The lenum parameter was invalid or lrecnum specied a record
marked for deletion.
Operation Notes
Not applicable to message les.
Related Information
Intrinsics
Commands
Manual
4-222
None
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
FREAD
FREAD
NM and CM callable.
Reads a logical record or portion of a record from a le to the stack.
Syntax
I16
I16V
UDS
I16V
transfercount:=FREAD(lenum,buer,length);
Functional Return
transfercount
16-bit signed integer (assigned functional return)
Note
If the le was opened with the nowait I/O option enabled, transfercount is
zero. The IOWAIT intrinsic can be used to determine the length of the data
transferred.
Returns the length of the data transferred to buer:
If a negative value is passed in the length parameter, transfercount is a
positive value indicating the number of bytes transferred.
If a positive value is passed in the length parameter, transfercount is a
positive value indicating the number of half words transferred.
If nowait I/O is specied in FOPEN/HPFOPEN, a zero is returned. The record
length is returned in the length parameter of the IOWAIT or IODONTWAIT
intrinsic.
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be read. If lenum references a directory
node, FREAD fails with a CCL le code.
user-dened structure (required)
Returns the record that was read. This structure must be large enough to
hold all of the information to be transferred.
Command Definitions
4-223
FREAD
length
16-bit signed integer by value (required)
Passes the length of the data to be transferred to buer:
Value
<0
=0
>0
Meaning
Length in bytes
No transfer occurs
Length in half words
If length is larger than the size of the logical record, and the multirecord
aoption in FOPEN/HPFOPEN was not specied, transfer is limited to the length
of the logical record. If the multirecord aoption in FOPEN/HPFOPEN is specied,
transfer continues until either length is satised or end-of-data is encountered,
and each transfer begins at the start of the next physical record (block).
Any data remaining in the last physical record read is inaccessible. Data
transfer for byte stream les continues until either length bytes are read or an
end-of-file occurs.
Operation Notes
When the logical end-of-data is encountered, CCG (0) is returned to the process:
On magnetic tape, the end-of-data is a physical indicator such as a tape mark. When
the program reads a le that spans more than one volume of labeled magnetic tape, the
program is suspended until an operator mounts the next tape. CCG (0) is not returned
when end-of-tape is encountered.
On disk, the end-of-data occurs when there is an attempt to read past the last logical record
of the le. In this case, CCG (0) is returned, and no record is read.
If the le is embedded in an input source containing commands, an end-of-data occurs
when an EOD command is encountered. End-of-data is indicated by a hardware end-of-le,
including EOF (on $STDIN), any record beginning with a colon (:), or on $STDINX, by EOD.
On a standard input device for a job (not a session) JOB, EOJ, or DATA indicate end-of-data.
4-224
Command Definitions
FREAD
When reading from an empty message le and another process has opened that le for write
access, the process waits. If the message le is empty and there are no writers, the process
waits if there is an FCONTROL=45 in eect or if this is the rst FREAD after the reader's
FOPEN/HPFOPEN. Otherwise, CCG (0) is returned. If an FREAD is issued against a message le
and an FCONTROL=46 is in eect, the writer's ID and the record type code are appended to the
beginning of the record.
When an old le containing carriage-control characters supplied through the controlcode
parameter of the FWRITE intrinsic is read, and you specied either the carriage-control foption
parameter of the FOPEN/HPFOPEN intrinsic, or the CCTL parameter of the FILE command, the
carriage-control byte is read as follows:
d
a
+-+----------------------------+
|C|
|
|C|
Data Read
|
|B|
|
+-+----------------------------+
c
CCB = Carriage Control Byte
b
Figure 4-8. Carriage Control Byte
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The information was read.
Request denied. The logical end-of-data was encountered during reading.
When reading a labeled magnetic tape le that spans more than one volume,
CCG (0) is not returned when end-of-tape (EOT) is encountered. CCG (0)
is returned at actual end-of-le, with a transmission log of 0 if there is an
attempt to read past end-of-le.
Request denied. The information was not read because a terminal read was
terminated by a special character or timeout interval, as specied in the
FCONTROL intrinsic, or a tape error was recovered and the FSETMODE option
was enabled. Check the condition codes both in normal I/O and in nowait
I/O.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-225
FREADBACKWARD
NM and CM callable.
Reads a logical record backward from the current record pointer. Data is presented as if read
forward. Used for tape les only. Can recover tape errors when handling I/O management
and data recovery routines.
Syntax
I16
I16V
UDS
I16V
transfercount:=FREADBACKWARD(lenum,buer,length);
Functional Return
transfercount
16-bit signed integer
Note
If the le is opened with the nowait I/O option enabled, transfercount is
zero. The IOWAIT intrinsic can be used to determine the length of the data
transferred.
Returns the length of the data transferred to buer:
If a negative value is passed in the length parameter, the transfercount is a
positive value indicating the number of bytes transferred.
If a positive value is passed in the length parameter, the transfercount is a
positive value indicating the number of half words transferred.
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be read.
user-dened structure (required)
Returns the specied record. This structure must be large enough to hold all
of the information to be returned.
4-226
Command Definitions
FREADBACKWARD
length
16-bit signed integer by value (required)
Returns the length of the data to be transferred to buer:
Value
<0
=0
>0
Meaning
Length in bytes
No transfer occurs
Length in half words
If length is larger than the size of the logical record, and the multirecord
aoption in FOPEN/HPFOPEN was not specied, transfer is limited to the length
of the logical record. If the multirecord aoption in FOPEN/HPFOPEN is specied,
transfer continues until either length is satised or end-of-data is encountered,
and each transfer begins at the start of the next physical record (block). Any
data remaining in the last physical record read is inaccessible.
Operation Notes
Three restrictions apply when using FREADBACKWARD:
Used only with a magnetic tape drive with read-reverse capability.
The magnetic tape drive must be located on an HP-IB system.
The magnetic tape NOBUF must be accessed.
Note
Magnetic tape devices with read-reverse capability are not supported. A call
to FREADBACKWARD results in an error (CCL (1)).
Not used for KSAM les.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The logical beginning-of-data was encountered. When
reading a labeled magnetic tape le that spans more than one volume, CCG
(0) is not returned when beginning-of-tape (BOT) is encountered. CCG (0) is
returned at actual beginning of le, with a transmission log of 0 if an attempt
is made to read past beginning-of-le.
Request denied. The information was not read because a tape error occurred,
or a tape error was recovered and the FSETMODE option was enabled. Check
the condition code in both normal I/O and nowait I/O.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-227
FREADBYKEY
NM and CM callable.
Reads a logical record randomly from a KSAM le to the data stack.
For KSAM les only.
Note
Syntax
I16V
I16V
LA
I16V
CA
length:=FREADBYKEY(lenum,target,tcount,keyvalue,);
I16V
keylocation);
Functional Return
length
16-bit signed integer by value (assigned functional return)
Returns the length of the information transferred. If tcount is positive, length
is a word count; if negative it is a byte count.
Parameters
lenum
16-bit signed integer by value (required)
target
Passes the le number of the le to be read.
logical array (required)
tcount
Contains the transferred record. It must be large enough to hold all the
information to be read.
16-bit signed integer by value (required)
Passes the number of words or bytes to be transferred. If tcount is positive,
it is the length in words; if negative, it is the length in bytes.
If tcount is less than the size of the record to be transferred, only the rst
tcount words or bytes are transferred from the record. If the tcount is larger
than the physical record size, only the physical record length is transferred.
4-228
Command Definitions
FREADBYKEY
keyvalue
character array (required)
keylocation
Passes the value determining the record to be read. The rst record found
with an identical value in the key specied by keylocation is the record read.
16-bit signed integer by value (required)
Passes the relative byte location in the record of the key whose value
determines which record is to be read. The rst byte is numbered as 1. If a
value of zero is specied, the primary key is used.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The logical end-of-data or beginning-of-data was encountered
during the read.
Request denied. An error occurred. Either an I/O error occurred or the key
could not be located.
Related Information
Intrinsics
Commands
Manuals
None
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
4-229
FREADC
NM and CM callable.
FREADC returns records in physical sequence, not chronological sequence. For KSAM/XL
les with the REUSE option, physical is not equal to chronological sequence and FREADC
reads the le in physical sequence. Deleted records are not returned using the FREADC
intrinsic, the FREADDIR intrinsic must be used if deleted records are required.
For KSAM les only.
Note
Syntax
I16V
I16V
LA
I16V
length:=FREADC(lenum,target,tcount);
Functional Return
length
16-bit signed integer by value (assigned functional return)
Returns the length of the information transferred. If tcount is positive, it is a
word count; if negative, it is a byte count.
Parameters
lenum
16-bit signed integer by value (required)
target
Passes the le number of the le to be read in chronological sequence.
logical array (required)
tcount
Returns the transferred record. It must be large enough to hold all the
information to be read.
16-bit signed integer by value (required)
Passes the number of words or bytes to be transferred. If tcount is positive,
it is the length in words; if negative, it is the length in bytes.
If tcount is less than the size of the record to be transferred, only the rst
tcount words are transferred from the record. If the tcount is larger than the
physical record size, only the physical record length is transferred.
4-230
Command Definitions
FREADC
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The logical end-of-data or beginning-of-data was encountered
during the read.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
4-231
FREADDIR
NM and CM callable.
Reads a specic logical record or portion of a record from a direct-access disk le to the data
stack.
Syntax
I16V
UDS
I16V
I32V
FREADDIR(lenum,buer,length,lrecnum);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be read.
user-dened structure (required)
length
Returns the record that was read. This structure should be large enough to
hold all of the information to be transferred.
16-bit signed integer by value (required)
Passes the number of half words or bytes to be transferred. If this value
is positive, it signies half words; if negative, bytes. Zero signies that no
transfer occurs. If length is less than the size of the logical record, only the
rst length half words or bytes are read from the record.
lrecnum
If length is larger than the size of the logical record and the multirecord
aoption in FOPEN/HPFOPEN was not specied, the transfer is limited to the
length of the logical record. If the multirecord aoption in FOPEN/HPFOPEN is
specied, the remaining half words or bytes specied in length are read from
the next records.
32-bit signed integer by value (required)
The relative number, in the le, of the logical record or block number for the
NOBUF les to be read. A value of zero indicates the rst logical record.
(KSAM) Indicates the relative chronological record number where the the
chronological pointer is positioned. Chronological record numbering for
xed-length records starts with 0 or 1, as specied when the le was built.
4-232
Command Definitions
FREADDIR
Operation Notes
This intrinsic is dierent than the FREAD intrinsic. The FREAD intrinsic reads only the record
already pointed to by the logical record pointer. Issue the FREADDIR intrinsic only for disk
les composed of xed-length or undened-length records. If RIO access is used, FREADDIR
inputs the specied logical record. If the record is inactive, the contents of the inactive record
are transmitted and CCE (2) is returned; there is no indication of the block containing some
inactive records. (FCHECK returns a nonzero error number to distinguish active and inactive
records.) If an RIO le is accessed using the non-RIO method (NOBUF), FREADDIR inputs the
specied block.
After the FREADDIR intrinsic is executed, the logical record pointer is set to the beginning of
the next logical record, or the rst logical record of the next block for NOBUF les.
It is possible to skip portions of records inadvertently, if the multirecord aoption of
FOPEN/HPFOPEN is set and the length parameter specied is greater than one logical record.
For example, if all of record 11 and half of record 12 is read in a le, the logical record pointer
is set to the beginning of record 13 after the FREADDIR intrinsic executes; the second half of
record 12 is skipped.
Byte stream les are applicable with FREADDIR intrinsic. Thelrecnum parameter species a
byte oset in the byte stream le, which is equivalent to a logical record number, since the
record size is one byte.
Not applicable to message les.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The information was read.
Request denied. End-of-le was encountered.
Request denied. The information was not read; an error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
4-233
FREADLABEL
NM and CM callable.
Reads a user-dened label from a disk or magnetic tape le.
Syntax
I16V
UDS I16V I16V
FREADLABEL( lenum,buer,length,labelid);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le whose label is to be read.
user-dened structure (required)
length
Returns the label that was read. This structure must be large enough to hold
the number of half words specied by length .
16-bit signed integer by value (optional)
labelid
Default: 128 half words
16-bit signed integer by value (optional)
Passes the number of half words to be transferred from the label, <=128.
Passes the label number. For labeled tapes, labelid is ignored. The next
sequential label is read.
Default: Zero
Operation Notes
When a disk le is opened, user labels can be read from, or written to, in any order, at any
time, regardless of access capabilities to the rest of the le. A disk le can have <=254
128-half word user-dened labels.
A magnetic tape le (if labeled) must be labeled with an ANSI-standard or IBM-standard
label. The operating system automatically skips over any unread user-dened labels when
the rst FREAD intrinsic call for les is issued. To read a user-dened label, you should call
the FREADLABEL intrinsic immediately after an FOPEN/HPFOPEN intrinsic has opened the
le. The user-dened label must be 40 half words in length to conform to the length of the
ANSI-standard or IBM-standard label.
4-234
Command Definitions
FREADLABEL
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The label was read.
Request denied. A label was referenced beyond the label written on the le.
Request denied. The label was not read; an error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-235
FREADSEEK
NM and CM callable.
Moves a record from a disk le to a buer in anticipation of a FREADDIR intrinsic call.
Syntax
I16V
I32V
FREADSEEK(lenum,lrecnum);
Parameters
lenum
16-bit signed integer by value (required)
lrecnum
Passes the le number of the le to be read.
32-bit signed integer by value (required)
Passes the relative number of the logical record to be read. A value of zero
indicates the rst logical record.
Operation Notes
The FREADSEEK intrinsic enhances direct access of disk les. When a certain record is
required, use FREADSEEK before a call to FREADDIR to transfer it to the stack. The FREADSEEK
intrinsic directs
the operating system to move the record from disk into a buer in anticipation of the
FREADDIR call, which moves the record directly to the stack.
Issue the FREADSEEK intrinsic call only for direct-access les where I/O buering and
xed-length or undened-length records are in eect.
FREADSEEK fails with a CCL condition code when lenum references a NOBUF le. Byte
stream les are opened NOBUF, and not applicable to FREADSEEK intrinsic.
Not applicable to message les.
(KSAM) This intrinsic cannot be used for KSAM les. If called for a le created as a KSAM
le, CCL (1) is returned.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-236
Request granted.
Request denied. A logical end-of-le indication was encountered.
Request denied. An error occurred.
Command Definitions
FREADSEEK
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-237
FREEDSEG
NM and CM callable.
Releases an extra data segment assigned it by the GETDSEG intrinsic. Data segment
management (DS) capability is required.
Data segment management (DS) intrinsics are not recommended for use in
the native mode programming environment. Use of DS intrinsics in NM will
degrade your program's performance.
Note
Syntax
U16V U16V
FREEDSEG(index,id);
Parameters
index
16-bit unsigned integer by value (required)
id
Passes the index assigned to the data segment, obtained from a GETDSEG
intrinsic call.
16-bit unsigned integer by value (required)
Passes the identication assigned to the segment. Enter zero if none is
assigned.
Operation Notes
If this is a private data segment or a shareable (nonprivate) segment not currently assigned to
any other process in the job/session, the segment is deleted from the entire job/session. If it is
a shareable segment that is currently assigned to another process, it is deleted from the calling
process but continues to exist in the job/session.
If the process is running in privileged mode when the extra data segment is acquired, then the
process must be in privileged mode when it invokes FREEDSEG.
4-238
Command Definitions
FREEDSEG
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The data segment is deleted from the job/session.
Request granted. The data segment is deleted from the calling process but
continues to exist in the job/session; it is being shared by another process.
Request denied. Either the index is invalid, or index and id do not specify
the same shared data segment.
Related Information
Intrinsics
Commands
Manuals
None
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
4-239
FREELOCRIN
NM and CM callable.
Frees all local resource identication numbers (RINs) from allocation to a job/session.
Syntax
FREELOCRIN;
Operation Notes
The FREELOCRIN intrinsic must be called before a second call to GETLOCRIN.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. No RINs are currently reserved for the job.
Request denied. A minimum of one RIN is currently locked by a process.
Related Information
Intrinsics
Commands
Manuals
4-240
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
FRELATE
FRELATE
NM and CM callable.
Determines whether a le pair (on any device) is interactive, duplicative, or both interactive
and duplicative.
Syntax
U16
I16V
I16V
intordup:=FRELATE(inlenum,listlenum);
Functional Return
intordup
16-bit unsigned integer (assigned functional return)
Returns values indicating whether the two les referenced are interactive
and/or duplicative:
Bits
Value/Meaning
15:1
0
Files specied by inlenum and listlenum do not form
an interactive pair.
1
Files specied by inlenum and listlenum form an
interactive pair.
0
Files specied by inlenum and listlenum do not form a
duplicative pair.
1
Files specied by inlenum and listlenum form a
duplicative pair.
0:1
Parameters
inlenum
16-bit signed integer by value (required)
listlenum
Passes the le number of the input le.
16-bit signed integer by value (required)
Passes the le number of the list le.
Command Definitions
4-241
FRELATE
Operation Notes
A device le is interactive if it requires human intervention for all input operations; this is
necessary to establish the person/machine dialog required to support a session.
A device le is duplicative if all input operations are echoed to a corresponding display
without intervention by the operating system software.
The interactive/duplicative attributes of a le pair do not change between the time the les
are opened and closed.
(KSAM) This intrinsic cannot be used for KSAM les. If called for a le created as a KSAM
le, CCL (1) is returned.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. Inlenum and/or listlenum corresponds to $NULL (a
logical le that contains no data). No data can be read from this le, and all
data written to it is discarded. Interactive or duplicative functions do not
apply.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
4-242
None
None
Accessing Files Programmer's Guide (32650-90017) and Getting System
Information Programmer's Guide (32650-90018)
Command Definitions
FREMOVE
FREMOVE
NM and CM callable.
Marks the current record in a KSAM le for deletion.
Note
For KSAM les only.
Syntax
I16V
FREMOVE(lenum)
Parameters
lenum
16-bit signed integer by value (required)
Passes the le number of the le where the record is to be deleted.
Operation Notes
Split stack calls are permitted.
Deleted records can be read with this intrinsic.
(KSAM/3000) When executed, the rst word of the current record is set to 1's; the record
is not physically deleted from the le. When the le is read by a KSAM read intrinsic, the
deleted records are not read.
(KSAM/XL) When executed, the rst bit in the record header is set to 1.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The logical end-of-data was encountered.
Request denied. An error was encountered or the record does not contain the
requested key value; the record is not deleted.
Related Information
Intrinsics
Commands
Manuals
None
None
Using KSAM XL (32650-90168) and KSAM/3000 Reference Manual
(30000-90079)
Command Definitions
4-243
FRENAME
NM and CM callable.
Renames an open disk le (and its lockword, if applicable). The le being renamed must be
either:
A new le.
An old le (permanent or temporary), opened for exclusive access with the exclusive option
of the HPFOPEN/FOPEN intrinsics, and with security provisions allowing write access.
Syntax
I16V
CA
FRENAME(lenum,formaldesig);
Parameters
lenum
16-bit signed integer by value (required)
formaldesig
Passes the le number of the le to be renamed.
character array (required)
Passes a formal le designator interpreted according to MPE-escaped
semantics. The le name must be terminated by a nonalphanumeric character
other than a period (.), a slash (/), a hyphen (-), and an underscore ( ).
The le referred to by formaldesig can be either an MPE le (i.e., one
that uses MPE syntax) or it can follow HFS syntax. If formaldesig follows
MPE syntax, the le name can include password, group, and account in the
following format:
lename/lockword.group.account
To keep or add a lockword to the le, enter it in the ASCII string. If you do
not specify a group, the le will remain in the same group it was assigned
before you invoked FRENAME. If you are renaming a new or temporary le,
specify any account that shares the same volume set as the le referred to by
formaldesig .
If formaldesig follows HFS syntax, the le name must start with either a dot
(.) or a slash (/).
If formaldesig is an escaped pathname:
you cannot reference remote les
it cannot express a name equivalent to lename :envid
you cannot use the device parameter (device =node #) to specify the remote
location of a device
4-244
Command Definitions
FRENAME
If formaldesig is the name of a user-dened le, it can begin with an asterisk
(*). If formaldesig is the name of a system-dened le, it can begin with a
dollar sign ($). When creating a KSAM le, formaldesig must be a unique le
name, that is, one not currently existing in the permanent le directory.
The formal le designator can contain command interpreter variables and
expressions that are evaluated before formaldesig is parsed and validated.
The le referred to by formaldesig may reside either in an MPE group or in
an HFS directory.
If renaming a le, a process must have the following:
TD
Traverse directory entry to access to all directories
specied informaldesig. If formaldesig is specied as
file.group.account, the directories are the root directory,
the account, and the MPE group. If there is no TD access,
FRENAME fails and a call to FCHECK with lenum set to 0 will
return a system error code (398) in the fserrorcode parameter.
CD
Create directory entry to access to the new parent directory.
DD
Delete directory entry to access to the old parent directory.
SF
Save les capability.
The le referred to by formaldesig may reside either in an MPE group or in
an HFS directory.
If a le is referenced by lenum, you can rename it within the hierarchical
directory as long as the process invoking FRENAME has sucient access and the
restrictions are satied. FRENAME intrinsic fully qualies the le owner name.
Only le owners and users with appropriate privilege can manipulate a le's
lockword.
The home volume set of formaldesig must be the same as the le being
renamed. Volume sets cannot be spanned when renaming les.
Operation Notes
The following restrictions apply toFRENAME:
Directories cannot be renamed.
Lockwords cannot be assigned to hierarchical directories.
Files cannot be renamed across volume sets.
Files with KSAM/3000, RIO, and CIR le types may only be assigned names in the MPE
name space.
If a le without an ACD is renamed from an MPE group to a directory (although not within
the same account), an ACD is automatically assigned to the le.
All errors will set the condition codes to CCL.
(KSAM) Although FRENAME will work on CM KSAM les, it renders them unuseable until
they are reassigned their original names. To rename a CM KSAM le, use the KSAMUTIL
RENAME command.
Command Definitions
4-245
FRENAME
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
4-246
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
FSETMODE
FSETMODE
NM and CM callable.
Controls the following access modes of les or devices:
Issuing carriage return and line feed to terminal after a terminal read.
Reporting tape automatic error recovery.
Guaranteeing chronological order of user program write requests.
Blocking program execution until physical completion of write requests.
Syntax
I16V
U16V
FSETMODE(lenum,modeags);
Parameters
lenum
16-bit signed integer by value (required)
modeags
Passes the le number of the le whose access modes are to be set.
16-bit unsigned integer by value (required)
Passes the access mode option:
Bits
Value/Meaning
15:1
Controls chronological order of user program writes. This
mode controls write requests to the le from all writers on the
system.
0
Do not change the write queue where this le is being
accessed
1
Access this le through the serial write queue
(ASC) Not used for asynchronous serial devices.
(KSAM) Set this bit to zero.
Note
A le placed on the serial write queue remains until the le is purged.
Command Definitions
4-247
FSETMODE
Bits
Value/Meaning
14:1
Controls blocking of program execution until completion of
physical write operations. This mode controls writes to lenum
only from the calling process.
0
Return control to the program from a write request
without waiting for completion of the physical write
operation
1
Force the program to wait until the physical write
operation is completed (the record is posted)
(ASC) Not used for asynchronous serial devices.
(KSAM) Bit (14:1) only is returned. The possible values are:
1
Activate output verication:
All output to the le is veried as physically complete
before an FWRITE, FUPDATE, or FREMOVE intrinsic returns
control to the user. When a logical record is written, a
CCE (2) condition is returned.
0
Deactivate output verication:
Output is not veried.
13:1
Controls issuing line feed to a terminal after each terminal read.
0
Issue a line feed at the completion of each read from a
terminal.
1
Inhibit issuance of a line feed at the completion of each
read from a terminal.
(KSAM) Set this bit to zero.
4-248
Command Definitions
FSETMODE
Bits
Value/Meaning
12:1
Reporting tape device automatic error recovery.
0
Do not report automatic error recovery on a tape device.
1
Report tape device automatic error recovery by returning
CCL (1) to FREAD and FWRITE.
(ASC) Not used for asynchronous serial devices.
0:12
(KSAM) Set this bit to zero.
Reserved for the operating system
Operation Notes
There are two ways to service a program's write request to a le:
In an order that maximizes overall system throughput, using the normal write queue.
In the order that the program requested the writes, using the serial write queue. Write
requests placed on the serial write queue are guaranteed to be completed in chronological
order.
FSETMODE intrinsic fails with a CCL condition:
If lenum references a byte stream le.
If FCHECK intrinsic is called to obtain the error code associated with a CCL condition code.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-249
FSPACE
NM and CM callable.
Moves a record pointer forward or backward on a magnetic tape or disk le, spaces physical
records on magnetic tape les and logical records on disk les.
Syntax
I16V
I16V
FSPACE(lenum,displacement);
Parameters
lenum
16-bit signed integer by value (required)
displacement
Passes the le number of the le on which spacing is to be done.
16-bit signed integer by value (required)
Passes the number of logical records for buered disk les, or blocks for NOBUF
les and all tape les, to be spaced over, relative to the current position of the
logical record pointer.
A positive value signies forward spacing, a negative value signies backward
spacing. The maximum positive value is 32,767, the maximum negative value
is -32,768.
If RIO access is used, displacement includes both active and inactive
records. Attempts to backspace beyond the beginning of the le are ignored
by the system. The logical record pointer points to record 0 (the rst record),
and no error codes are returned.
Operation Notes
The FSPACE intrinsic cannot be used with variable-length record les, message les, or with
spooled les on disk. An attempt to use this intrinsic on such les results in CCL (1), and the
logical record pointer is left at its current position.
FSPACE intrinsic fails with a CCL condition:
If lenum references a byte stream le.
If FCHECK intrinsic is called to obtain the error code associated with a CCL condition code.
(KSAM) The logical record pointer is repositioned in key sequence. The spacing is based
on the primary key unless an alternate key has been specied in a prior call to FFINDN,
FFINDBYKEY, or FREADBYKEY.
4-250
Command Definitions
FSPACE
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. An end-of-le indicator was encountered during spacing. For
disk les, this is the le limit, and the logical record pointer is not changed.
For magnetic tape les, this is the end-of-le mark, and the logical record
pointer points to the (logical) end-of-le. The magnetic tape is positioned to
one record past the le mark on the tape. For labeled tape, the logical record
pointer is at the le mark.
Request denied. An error occurred; for example, the le resides on a device
that prohibits spacing. Not allowed with append access.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
4-251
FUNLOCK
NM and CM callable.
Dynamically unlocks a le's global resource identication number (RIN) that was locked with
the FLOCK intrinsic.
Syntax
I16V
FUNLOCK(lenum);
Parameters
lenum
16-bit signed integer by value (required)
Passes the le number of the le whose global RIN is to be unlocked.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The calling process did not lock the le.
Request denied. The le was not opened with the dynamic locking aoption of
the FOPEN/HPFOPEN intrinsic, or the lenum parameter is invalid.
Related Information
Intrinsics
Commands
Manuals
4-252
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
FUPDATE
FUPDATE
NM and CM callable.
Updates (writes) a logical record in a disk le.
Syntax
I16V UDS I16V
FUPDATE(lenum,buer,length);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be updated.
user-dened structure (required)
length
Passes the record to be written in the update.
16-bit signed integer by value (required)
Passes the number of half words or bytes to be written to the le. A positive
value is in half words; a negative value is in bytes.
For les opened BUF:
If length <= record size, the length is transferred in half words or bytes
and remaining portions of the record are padded with ll characters.
If length = 0, no transfer occurs, and the record address is overwritten with
default ll characters (blanks for ASCII les and null characters for binary
les).
If length > record size, CCL (1) is returned and no transfer occurs.
For les opened NOBUF:
If length <= block size, the length is transferred in half words or bytes and
remaining portions of the record are padded with ll characters.
If length > block size, CCL (1) is returned and no transfer occurs.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. An end-of-le condition was encountered during updating.
Request denied. An error occurred; the le is not residing on disk, or length
exceeds the size of the block when multirecord mode is not in eect.
Command Definitions
4-253
FUPDATE
Operation Notes
This intrinsic aects the logical record (or block for NOBUF les) of the le last referenced
by any intrinsic call, except an FPOINT call, which aects the record prior to the last
record referenced. FUPDATE moves the specied information from the stack into this record.
The le containing this record must be opened with the update aoption specied in the
FOPEN/HPFOPEN call and the le cannot have variable-length records. If RIO access is used,
the modied record is set to the ACTIVE state.
FUPDATE intrinsic fails with a CCL condition:
If lenum references a byte stream le.
If FCHECK intrinsic is called to obtain the error code associated with a CCL condition code.
The FUPDATE intrinsic is not applicable to message les.
Related Information
Intrinsics
Commands
Manuals
4-254
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
FWRITE
FWRITE
NM and CM callable.
Writes a logical or physical record or portion of a record from the stack to a le on any device.
Syntax
I16V UDS I16V
U16V
FWRITE(lenum,buer,length,controlcode);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be written on.
user-dened structure (required)
length
Passes the record to be written.
16-bit signed integer by value (required)
Passes the number of half words or bytes to be written to the record. If this
value is positive, it signies half words; if negative, bytes. Zero indicates that
no transfer occurs.
If length is less than the recsize parameter associated with the record, only
the rst length (half words or bytes) is written.
If length is larger than the logical record size and NOBUF (aoption in
FOPEN/HPFOPEN) is not specied, the FWRITE request is refused and CCL (1) is
returned. If NOBUF is specied, length cannot exceed the physical record size
unless the multirecord aoption is specied also.
If the multirecord aoption in FOPEN/HPFOPEN is specied, the excess half
words or bytes are written to succeeding physical records and carriage-control
is specied, the actual data transferred is limited to recsize minus one byte.
(ASC) For asynchronous devices, the physical data transfer is byte-by-byte. If
half words are specied, an even number of bytes is output.
Command Definitions
4-255
FWRITE
controlcode
16-bit unsigned integer by value (required)
Passes a carriage-control code, eective if the le is transferred to a line
printer or terminal (including a spooled le whose destination is a line
printer or a terminal). This parameter is eective only for les opened with
carriage-control specied.
The options are:
Value
0
1
Meaning
Print the full record transferred, using single spacing. This
results in a maximum of 132 characters per printed line.
Use the rst character of the data written to satisfy space
control and suppress this character on the printed output. This
results in a maximum of 132 characters of data per printed line.
Use any octal code from Table 4-10 to determine space control and print
the full record transferred. This results in a maximum of 132 characters per
printed line.
If the controlcode parameter is not 0 or 1, and length is 0, only the space
control is executed and no data is transferred.
Determine whether the carriage-control directive takes eect before printing
(prespace movement) or after printing (postspace movement), with the
FCONTROL intrinsic.
For spooled les, use FWRITE instead of FCONTROL to set the
prespace/postspace control and the auto/no auto page eject control; use
control codes %100 through %103 and %400 through %403 for this. If one of
the above controls is specied with length=0, no physical I/O occurs.
4-256
Command Definitions
FWRITE
When a le is opened with CCTL, use the carriage-control codes in one of the
following ways:
As the value of the controlcode parameter.
When controlcode =1, as the rst byte of the buer array.
The default carriage-control code is postspacing with automatic page eject.
This applies to all Hewlett-Packard subsystems except
FORTRAN 77/XL and COBOLII/XL (these have prespacing with automatic
page eject).
Note
Channel assignments shown in Table 4-10 are the Hewlett-Packard standard
defaults.
(KSAM) This parameter must be specied to satisfy internal requirements, but it is ignored.
Command Definitions
4-257
FWRITE
Table 4-10. Carriage-Control Directives
Octal Code
(ASCII)
Description of Carriage Action
%2 - %52 (" ")
Single space (with or without automatic page eject)
%53 ("+")
No space (next printing at column 1), cannot be used more than once on the
Hewlett-Packard 2608A/S without losing data
%54 (" ")
Single space (with or without automatic page eject)
%55 ("-")
Triple space (with or without automatic page eject)
%56 - %57 (" ")
Single space (with or without automatic page eject)
%60 ("0")
Double space (with or without automatic page eject)
%61 ("1")
Conditional page eject (form feed) performed by the software; if the printer is not
at top-of-form, a page eject is performed. Ignored if:
Postspace mode The current request has a transfer count of 0 and the previous
request was FOPEN, HPFOPEN, FCLOSE, or FWRITE specifying a
carriage-control directive of %61.
Prespace mode The previous request has a transfer count of 0, and the current
request and previous request are any combination of FOPEN,
HPFOPEN, FCLOSE, or FWRITE specifying a carriage-control
directive of %61.
%62
Skip to one line before top of form (valid for Hewlett-Packard 2608S and 2563A
printers only)
%63
A conditional page eject form feed is performed by the printer; not at
top-of-form, a page eject is performed (valid for Hewlett-Packard 2608S and
2563A printers only)
%62 - %77 (" ")
Single space (with or without automatic page eject; for terminals and serial
printers)
%104 - %177 (" ") Single space (with or without automatic page eject; for terminals and serial
printers)
%2nn
Space nn lines (no automatic page eject); nn is any octal number from 0 through
77
%300 - %313
Select VFC Channel 1 - 12 (Hewlett-Packard 2613, 2617, 2618, 2619)
%300 - %317
Select VFC Channel 1 - 16 (Hewlett-Packard 2608A/S)
%300
Skip to top of form (page eject)
%301
Skip to bottom of form
%302
Single spacing with automatic page eject
%303
Skip to next odd line with automatic page eject
%304
Skip to next third line with automatic page eject
%305
Skip to next 1/2 page
%306
Skip to next 1/4 page
%307
Skip to next 1/6 page
%310
4-258
Skip to bottom of form
Command Definitions
FWRITE
Table 4-10. Carriage-Control Directives (continued)
Octal Code
(ASCII)
Description of Carriage Action
%311
User option (Hewlett-Packard 2613/17/18/19), skip to one line before bottom of
form (Hewlett-Packard 2608A/S)
%312
User option (Hewlett-Packard 2613/17/18/19), skip to one line before top of form
(Hewlett-Packard 2608A/S)
%313
User option (Hewlett-Packard 2613/17/18/19), skip to top of form
(Hewlett-Packard 2608A)
%314
Skip to next seventh line with automatic page eject
%315
Skip to next sixth line with automatic page eject
%316
Skip to next fth line with automatic page eject
%317
Skip to next fourth line with automatic page eject
%310 - %317
(Hewlett-Packard 2607)
%314 - %317
(Hewlett-Packard 2613/17/18/19)
%320
No space, no return (next printing physically follows this)
%321-%377 (" ")
Single space (with or without automatic page eject)
%400 or %100
Set postspace movement option (prints rst, then spaces). If previous option was
prespace movement, the driver outputs a line with a skip to VFC Channel 3
(automatic page eject in eect) or a one line advance (equivalent to an octal code
of %201 without automatic page eject) to clear the buer
%401 or %101
Set prespace movement option (spaces rst, then prints)
%402 or %102
Set single-space option, with automatic page eject (60 lines per page)
%403 or %103
Set single-space option, without automatic page eject (66 lines per page)
Note
If octal codes %55 and %60 are selected with automatic page eject in eect
(by default or following an octal code of %102 or %402), the resulting skip is
to a location absolute to the page. A code of %60 is replaced by %303, and a
code of %55 is replaced by %304. Therefore, the resulting skip can be less
than two or three lines, respectively.
If automatic page eject is not in eect, a true double or triple space results,
but the perforation between pages is not automatically skipped. For the
Hewlett-Packard 2608S and 2563A, if auto-eject and feature mode are in
eect, a code of %60 is replaced by two codes of %302, and a code of %55 is
replaced by three codes of %302. The resulting skip is double or triple space
with auto-eject, respectively.
Command Definitions
4-259
FWRITE
Figure 4-9. Carriage-Control Data
4-260
Command Definitions
FWRITE
Operation Notes
If information is written to a xed-length record and the NOBUF aoption in FOPEN/HPFOPEN is
not specied, any unused portion of the record is padded with binary zeros or ASCII blanks.
When the FWRITE intrinsic is executed, the logical record pointer is set to the record
immediately following the record just written, or to the rst logical record in the next block
for NOBUF les. If RIO access is used, the modied record is set to the ACTIVE state.
When an FWRITE call writes a record beyond the current logical end-of-le indicator, this
indicator is advanced. However, this is noted in the le label only when the le is closed
or when an extent is allocated. If the physical bounds of the le are reached, CCG (0) is
returned.
If a magnetic tape is unlabeled (as specied in the FOPEN/HPFOPEN intrinsic, or in the FILE
command) and the program attempts to write over or beyond the physical or simulated
end-of-tape (EOT) marker, the FWRITE intrinsic returns CCL (1). The actual data is written
to the tape, and a call to FCHECK reveals an end-of-tape le error. After the EOT marker is
crossed, all writes to the tape transfer the data successfully but return CCL (1) until the tape
crosses the EOT marker again in the reverse direction (rewind or backspace).
If a magnetic tape is labeled (as specied in the FOPEN/HPFOPEN intrinsic, or in the FILE
command), CCL (1) is not returned when the tape passes the EOT marker. Attempts to
write to the tape after an EOT marker cause end-of-volume (EOV) markers to be written. A
message is printed on the system console requesting another volume (reel of tape) be mounted.
For message les and circular les, this intrinsic logically appends the record to the end of the
le. If a circular le is full, the rst block is deleted, the remaining blocks are logically shifted
to the le's head, and the new record is appended to the end of the le. If a message le is
full and there are no readers, the process waits if there is an FCONTROL=45 in eect or if this is
the rst FWRITE after an FOPEN/HPFOPEN call. Otherwise, CCG (0) is returned.
Control codes are ignored for byte stream les. Byte stream les can not be opened with
carriage control.
Command Definitions
4-261
FWRITE
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The physical bounds of the le prevented further writing.
Request denied. An error occurred; length exceeded the size of the record in
nonmultirecord mode, the FSETMODE option was enabled to signify recovered
tape errors, or the end-of-tape marker was sensed. If the le is being written
to a multivolume labeled magnetic tape set, CCL (1) is not returned when the
end-of-tape marker is sensed. Instead, end-of-volume labels are written, and a
request is issued to mount the next volume.
Related Information
Intrinsics
Commands
Manuals
4-262
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
FWRITEDIR
FWRITEDIR
NM and CM callable.
Writes a specic logical record from the stack to a disk le.
Syntax
I16V UDS
I16V
I32V
FWRITEDIR(lenum,buer,length,lrecnum);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be written to.
user-dened structure (required)
length
Passes the record to be written. This structure should be large enough to hold
all of the information to be transferred.
16-bit signed integer by value (required)
Passes the number of half words or bytes to be written to the le. A positive
value is in half words; a negative value is in bytes.
For les opened BUF:
If length <= record size, the length is transferred in half words or bytes
and remaining portions of the record is padded with ll characters.
If length = 0, no transfer occurs and the record address is overwritten with
default ll characters (blanks for ASCII les; null characters for binary
les).
If length > record size, CCL (1) is returned and no transfer occurs.
lrecnum
For les opened NOBUF and nonmultirecord:
Length is transferred in half words or bytes up to the le limit (ignores
all block boundaries) and remaining portions of the last block written to is
padded with ll characters.
32-bit signed integer by value (required)
Passes the relative number of the logical record, or block number for NOBUF
les, to be written. Zero indicates the rst record.
Command Definitions
4-263
FWRITEDIR
Operation Notes
This intrinsic diers from the FWRITE intrinsic, the FWRITE intrinsic writes only the record
pointed to by the logical record pointer. Use the FWRITEDIR intrinsic only for disk les
composed of xed-length or undened-length records.
When information is written to a xed-length record and NOBUF is not specied in the
FOPEN/HPFOPEN call that opens the le, any unused portion of the record is padded with
binary zeros or ASCII blanks.
When the FWRITEDIR intrinsic is executed, the logical record pointer is set to the record
immediately following the record just written, or the rst logical record of the next block for
NOBUF les.
If RIO access is used, the modied record is set to the ACTIVE state.
When an FWRITEDIR call writes a record beyond the current logical end-of-le indicator, the
indicator is advanced. This can result in the creation of dummy records to pad the records
between the previous end-of-le and the newly written record. When the new record is in the
same extent, these dummy records are lled with binary zeros or with ASCII blanks.
When the physical bounds of the le prevent further writing because all allowable extents are
lled, the end-of-le condition (CCG (0)) is returned to the program.
Not applicable to message les.
(KSAM) This intrinsic cannot be used for KSAM les. If called for a le created as a KSAM
le, CCL (1) is returned.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The physical end-of-le was encountered.
Request denied. An error occurred.
Related Information
Intrinsics
Commands
Manuals
4-264
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
FWRITELABEL
FWRITELABEL
NM and CM callable.
Writes a user-dened label onto a disk le or magnetic tape le that is labeled with an
ANSI-standard or IBM-standard label. It also overwrites old user labels.
Syntax
I16V
UDS I16V I16V
FWRITELABEL(lenum,buer,length,labelid);
Parameters
lenum
16-bit signed integer by value (required)
buer
Passes the le number of the le to be labeled.
user-dened structure (required)
length
Passes the label to be written. If the le is a labeled magnetic tape le, this
label must be 40 half words in length.
16-bit signed integer by value (optional)
labelid
Passes the number of half words or bytes passed by buer. A positive value
is in half words; a negative value is in bytes.
16-bit signed integer by value (optional)
Passes the number of the label to be written. The rst label is zero. This
parameter is ignored for labeled tapes. The next sequential tape label is
written. The default is zero.
Operation Notes
Once a disk le is opened, it is possible to read from or write to user-dened labels regardless
of the access to the rest of the le. If the le is on labeled magnetic tape, the user-dened
label must be 40 half words in length to conform to the length of the ANSI-standard or
IBM-standard label.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The calling process attempted to write a label beyond the
limit specied in the FOPEN/HPFOPEN intrinsic when the le was created.
Request denied. An error occurred.
Command Definitions
4-265
FWRITELABEL
Related Information
Intrinsics
Commands
Manuals
4-266
None
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
GENMESSAGE
GENMESSAGE
NM and CM callable (dierences noted below).
Provides access to messages in catalogs that were formatted with the MAKECAT utility.
Syntax
I16
I16V
I16V
I16V
msglength:=GENMESSAGE(lenum,setnum,msgnum,
CA I16V
I16V
buer,buersize,parmask,
*
*
*
I16V
*
*
param1,param2,param3,param4
param5,msgdestination,
I16
errornum);
Functional Return
msglength
16-bit signed integer (assigned functional return)
Returns the length of the message (in bytes).
Parameters
lenum
16-bit signed integer by value (required)
setnum
Passes the le number that species the message catalog.
Positive 16-bit signed integer by value (required)
msgnum
Passes the message set number within the catalog (>0,<63).
Positive 16-bit signed integer by value (required)
buer
Passes the message number within the message set (>0,<32767).
character array (optional)
buersize
Returns the assembled message.
16-bit signed integer by value (optional)
Returns the length of buer . If buer is specied, the length is in bytes.
If buer is not specied, returns the length (in bytes) of the records to be
written to the destination le.
Default: 72 bytes
(For a single-line message, the combined length of the message number, a
blank space separator, and message text must not exceed the default buer
size of 72 bytes.)
Command Definitions
4-267
GENMESSAGE
parmask
16-bit signed integer by value (optional)
Passes a mask indicating parameter types for param1 through param5 . The
bit settings are:
Bits
13:3
10:3
7:3
4:3
1:3
0:1
Value/Meaning
param5 type:
000 String, terminated by an ASCII null (0)
001 16-bit signed integer
010 32-bit signed integer by reference
011 Ignored
param4 type:
000 String, terminated by an ASCII null (0)
001 16-bit signed integer
010 32-bit signed integer by reference
011 Ignored
param3 type:
000 String, terminated by an ASCII null (0)
001 16-bit signed integer
010 32-bit signed integer by reference
011 Ignored
param2 type:
000 String, terminated by an ASCII null (0)
001 16-bit signed integer
010 32-bit signed integer by reference
011 Ignored
param1 type:
000 String, terminated by an ASCII null (0)
001 16-bit signed integer
010 32-bit signed integer by reference
011 Ignored
value:
1
Ignore rest of word and parameters param1 through
param5
0
Rest of word, in 3-bit groupings, species parameter types
for param1 through param5
Default: param1 through param5 are ignored.
4-268
Command Definitions
GENMESSAGE
param1
through
param5
type varies (optional)
(NM) Passes the parameter to be inserted into the message. If parmask is
000 (string), pass the 32-bit address of the array containing the string. If
parmask is 001 (16-bit signed integer), pass a signed 16-bit integer (a value
from -32,768 through 32,767). If parmask is 010 (32-bit signed integer by
reference), pass the 16-bit address of the word identier that returns the
value.
(CM) Passes the parameter to be inserted into the message. If parmask is
000 (string), pass the 16-bit address of the array containing the string. If
parmask is 001 (16-bit signed integer), pass a signed 16-bit integer (a value
from -32,768 through 32,767). If parmask is 010 (16-bit signed integer by
reference), pass the 16-bit address of the word identier that returns the
value.
msgdestination 16-bit signed integer by value (optional)
Returns the le number of the message's destination le (0 or -1=$STDLIST,
>2=le number of the destination le).
Default: $STDLIST if you do not specify buer , no le if you do specify buer .
Command Definitions
4-269
GENMESSAGE
errornum
16-bit signed integer by reference (optional)
Returns one of the following values, indicating the success or failure of the
intrinsic call.
Value
Meaning
0
1
2
3
4
6
Successful
7
8
11
12
13
14
15
16
17
18
19
FREADLABEL call on catalog le failed
FREAD call on catalog le failed
Specied setnum not found in catalog
Specied msgnum not found in catalog
Message overowed buer (if msgdestination specied, message
routed correctly)
Write to destination le failed
Catalog le opened with improper access options
lenum was not specied
setnum was not specied
msgnum was not specied
setnum < 0 was specied
setnum > 62 was specied
msgnum <= 0 was specied
buersize <= 0 was specied
msgdestination <= -2 was specied
Reference parameter out of bounds
Operation Notes
The calling program opens a message catalog, allowing the insertion parameters supplied
by GENMESSAGE. Depending on how the msgdestination and buer parameters are dened,
GENMESSAGE then routes the message to its destination. To route the message to a le, specify
msgdestination . To return the message to a calling program, specify buer . To do both,
specify both msgdestination and buer .
Open the catalog le as a permanent ASCII le with the NOBUF and MULTI access options
enabled.
4-270
Command Definitions
GENMESSAGE
Condition Codes
CCE (2)
CCL (1)
CCG (0)
Request granted.
Request denied. File system error.
Request denied. Missing required parameter, invalid parameter, or invalid le
number of catalog or destination le.
Related Information
Intrinsics
Commands
Manuals
None
None
Message Catalogs Programmer's Guide (32650-90021)
Command Definitions
4-271
GETDSEG
NM and CM callable.
Creates or acquires an extra data segment for use by the process. Data segment management
(DS) capability is required.
Data segment management (DS) intrinsics are not recommended for use in
native mode programming environment. Use of DS intrinsics in NM degrades
your program's performance.
Note
Syntax
U16
I16
U16V
GETDSEG(index,length,id);
Parameters
index
16-bit unsigned integer by reference (required)
length
Returns the index of the extra data segment assigned by the operating
system. When GETDSEG is called in user mode, index is a logical index of the
assigned data segment; if an error is found, index is set to %2000-%2004.
When GETDSEG is called in privileged mode, index is the actual data segment
table (DST) entry number assigned for the data segment.
16-bit signed integer by reference (required)
id
Passes the user-specied maximum size, in half words, of the newly created
data segment. If the data segment already exists, length returns the
maximum size, in half words, of the data segment.
16-bit unsigned integer by value (required)
Passes the identity that declares the extra data segment shareable between
other processes in the job/session, or private to the calling process. For a
shareable extra data segment, specify id as a nonzero value. If an extra data
segment with the same identication already exists, it is made available to the
calling process; otherwise, a new extra data segment, shareable within the
job/session, is created with id. For a private extra data segment, specify an
id of zero.
4-272
Command Definitions
GETDSEG
Operation Notes
The number of extra data segments that can be requested, and the maximum size allowed
these segments, is limited by parameters specied when the system is congured. When an
extra data segment is created, the GETDSEG intrinsic returns a logical index number to the
process. This index number is assigned by the operating system and allows the process to
reference the extra data segment in later intrinsic calls.
Assign the extra data segment to an identity that either allows other processes in the job or
session to share the extra data segment, or that declares it private to the calling process. If
the extra data segment is shareable, other processes can obtain its index (through GETDSEG)
and use this index to reference the extra data segment. Thus, the index is a local name that
identies the extra data segment throughout any process that obtained the index with the
GETDSEG call. The index does not need to be the same value in all processes sharing the extra
data segment. However, the identity is a job-wide or session-wide name that permits any
process to determine the index of the extra data segment. If GETDSEG is called in user mode,
the extra data segment is initially lled with zeros.
When GETDSEG is called in user mode, all subsequent calls to intrinsics that use index must
be in user mode. When GETDSEG is called in privileged mode, all subsequent calls to intrinsics
that use index must be in privileged mode.
When a data segment is created through GETDSEG, sucient virtual space is allocated by
the system to accommodate the original length of the data segment. This virtual space is
allocated in increments of 512 half words. For example, creation of an extra data segment
with a length of 600 half words results in the allocation of 1024 half words of virtual space.
Command Definitions
4-273
GETDSEG
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. A new extra data segment was created.
Request granted. An extra data segment with this identity exists already.
Request denied. The following values are returned in index:
Value
%2000
%2001
%2002
%2003
%2004
Meaning
An illegal length was specied.
The process requested more than the maximum allowable
number of data segments.
Sucient storage was not available for the data segment.
A stack expansion necessary to satisfy the request could not be
done because the stack was frozen or the stack is already at its
maximum size (stack expansion is usually not necessary to get
an extra data segment).
There is not enough room in the job denition table to make
an entry for the extra data segment.
Related Information
Intrinsics
Commands
Manuals
4-274
None
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
GETINFO
GETINFO
NM and CM callable.
Returns user-supplied information that was passed to a process when it was created.
Syntax
I16
CA
I16
I16
result:=GETINFO(infostring,infolength,parm);
Functional Return
result
16-bit signed integer (assigned functional return)
Returns an execution value:
Value
0
1
Meaning
Successful execution.
Execution error, one of the following conditions exist:
Infostring was specied, but infolength was not specied.
Infolength was specied, but infostring was not specied.
Either an invalid infostring or infolength value was specied.
An invalid parm value was specied.
Parameters
infostring
character array (optional)
Returns an information string (the contents of an array) passed to the calling
process by the info parameter of the RUN command, or by the item associated
with itemnum 11 of the CREATEPROCESS intrinsic.
If the information string was not supplied at process creation time, or if it is
of length zero, infostring is returned unmodied.
If infostring is specied, infolength must pass the length, in bytes, of
infostring .
Command Definitions
4-275
GETINFO
infolength
16-bit signed integer by reference (optional)
Passes and receives a value.
If infostring is specied, infolength must pass the length, in bytes, of
infostring .
When returning from the call, infolength contains the smaller of either the
length of the information string returned in infostring or the original value of
infolength .
Note
Specify a value at least as large as the length of the information string
supplied at process creation time. If infolength is too small, the information
string is truncated upon return to infostring .
Infostring and infolength must be specied as a pair.
parm
16-bit signed integer by reference (optional)
Returns a value passed to the calling process at process creation time by one
of the following sources:
The parm parameter of the RUN command.
The item associated with itemnum 2 of the CREATEPROCESS intrinsic.
The param parameter of the CREATE intrinsic.
A zero is returned if none of the above are used to pass a value.
Operation Notes
Returns user-supplied information to the calling process from one of the following sources:
If the process was created with the RUN command, the contents of the info and parm
parameters can be retrieved.
If the process was created with the CREATEPROCESS intrinsic, retrieve the items associated
with itemnum s 11 and 2.
If the process was created with the CREATE intrinsic, retrieve the contents of the param
parameter.
Related Information
Intrinsics
Commands
Manuals
4-276
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
GETJCW
GETJCW
NM and CM callable.
Returns the value of the system-dened job control word (JCW) to the calling process.
Syntax
U16
jcw:=GETJCW;
Functional Return
jcw
16-bit unsigned integer (assigned functional return)
Returns the JCW. This word is structured by the calling program through the
SETJCW or PUTJCW intrinsic.
Related Information
Intrinsics
Commands
Manuals
FINDJCW, PUTJCW, SETJCW
SETJCW, SHOWJCW
Interprocess Communication Programmer's Guide (32650-90019)
and Command Interpreter Access and Variables Programmer's Guide
(32650-90011)
Command Definitions
4-277
GETLOCRIN
NM and CM callable.
Acquires local resource identication numbers (RINs) for a job/session.
Syntax
U16V
GETLOCRIN(rincount);
Parameters
rincount
16-bit unsigned integer by value (required)
Passes the number of local RINs to be acquired by the job/session. The
maximum number of RINs available is dened when the system is congured.
Operation Notes
All local RINs required by a job/session must be acquired in a single call to GETLOCRIN. If
more local RINs are required, all local RINs must be released with the FREELOCRIN intrinsic
before GETLOCRIN can return more.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. RINs already allocated to this job. Additional RINs cannot
be allocated until these RINs are released.
Request denied. There are not enough RINs available for this call. RINs not
allocated to this job.
Related Information
Intrinsics
Commands
Manuals
4-278
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
GETORIGIN
GETORIGIN
NM and CM callable.
Returns the source of the activation call for the calling process that has been previously
suspended and subsequently reactivated. The source of the activation request can be the
parent process, a child process, or another source (for example, an interrupt or the timer).
Process handling (PH) capability is required.
Syntax
I16
source:=GETORIGIN;
Functional Return
source
16-bit signed integer (assigned functional return)
Returns one of the following values:
Value
0
1
2
Meaning
Was not activated by either the parent or a child process
Activated by the parent process
Activated by a child process
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-279
GETPRIORITY
NM and CM callable.
Changes the priority of a process. Process handling (PH) capability is required.
Syntax
I16V U16V
I16V
GETPRIORITY( pin,priorityclass,rank);
Parameters
pin
16-bit signed integer by value (required)
priorityclass
Passes the process whose priority is to be changed. To specify the calling
process, set pin to zero. To specify a child process, set pin to the process
identication number (PIN) of a child process.
16-bit unsigned integer by value (required)
Contains the priority class in which the new process is scheduled (AS, BS, CS,
DS, ES), computed in the following manner:
(ASCII of first character * 256) +
(ASCII of second character)
The integer equivalents are:
AS
BS
CS
DS
ES
=
=
=
=
=
16,723
16,979
17,235
17,491
17,747
Aborts the calling process if priorityclass exceeds the maximum allowable
priority class of the rescheduled process or species an invalid priority class.
Specify any priority class except AS, if in user mode; this function is limited
by the maximum priority assigned to the account by the system manager. If
in privileged mode, processes can be scheduled into all subqueues including
AS. Processes in the linear queues, AS or BS, do not give up the CPU
voluntarily; it could loop indenitely and prevent other processes from
accessing the CPU.
4-280
Command Definitions
GETPRIORITY
If in privileged mode, specify the priorityclass parameter as an absolute
priority by x A, where x is an 8-bit priority number and A is the ASCII
character A. For example, to request a priority class of 31 in the master
queue, set priorityclass to %017501. An absolute priority must be specied
in order to overcome the MAXPRI setting of an account.
Default: The priority class of the calling process
Note
Scheduling a process into the AS or BS priority class can result in the
rescheduled process deadlocking the system or locking out system and user
processes from execution.
rank
16-bit signed integer by value (optional)
Used for backward-compatibility with pre-MPE IV operating systems only.
Operation Notes
A process must be running in privileged mode to specify absolute priority.
A process can change its own priority or that of its child, but it cannot reschedule its parent.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The process specied is not currently accessible (for example,
unborn or dying).
Request denied. An illegal or invalid PIN was specied.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-281
GETPRIVMODE
NM and CM callable.
Dynamically enters privileged mode. Privileged mode (PM) capability is required.
Caution
Normal operating system checks and limitations are bypassed in privileged
mode (PM). It is possible for a PM program to destroy le integrity, including
the operating system software itself. Hewlett-Packard will investigate and
attempt to resolve problems resulting from the use of PM 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 modication of the operating system software.
Syntax
GETPRIVMODE;
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The program was in nonprivileged mode at the time of the
intrinsic call.
Request granted. The program was already in privileged mode at the time of
the intrinsic call.
Not returned.
Operation Notes
After a successful call to GETPRIVMODE, the program remains in privileged mode until a
call to GETUSERMODE or the program exits the current procedure. (A procedure refers to
a Pascal procedure or function, a C function, a Fortran subprogram, an SPL procedure, or a
COBOL program). Any procedures called while in privileged mode will execute in privileged
mode. When the procedure that called GETPRIVMODE exits, the previous privilege level is
restored.
Related Information
Intrinsics
Commands
Manuals
4-282
None
None
None
Command Definitions
GETPROCID
GETPROCID
NM and CM callable.
Returns the process identication number (PIN) of a child process. Process handling (PH)
capability is required.
Syntax
I16
I16V
pin:=GETPROCID(numchild);
Functional Return
pin
16-bit signed integer (assigned functional return)
Returns the PIN of the specied child process.
Parameters
numchild
16-bit signed integer by value (required)
Passes a number indicating which child's PIN GETPROCID returns. The value
of numchild corresponds to the order of creation of the current children of
the calling process, as follows:
Value
<=1
2
.
.
.
n
>n
Meaning
PIN of the oldest child process
PIN of second oldest child process
.
.
.
PIN of the most recently created child process (where n is the
number of children currently in existence)
A value greater than the number of children in existence,
returns a zero.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-283
GETPROCINFO
NM and CM callable.
Returns status information about the parent or a child process. Process handling (PH)
capability is required.
Syntax
I32
I16V
processinfo:=GETPROCINFO(pin);
Functional Return
processinfo
32-bit signed integer (assigned functional return)
Returns the process management information about a parent or child process:
Bits
Value/Meaning
29:2
0
Process suspended
1
Process active
Suspension condition:
31:1
Activity state:
If bit (31:1)=0:
4-284
25:4
23:2
00 Not used
01 Parent activation source
10 Child activation source
11 Either parent or child activation source
Reserved for the operating system
Origin of the last ACTIVATE intrinsic call:
20:3
00 operatiang system activation
01 Parent activation
10 Child activation
11 Not used
Queue characteristics:
16:4
8:8
0:8
001 DS or ES priority class
010 CS priority class
100 Linearly scheduled (AS, BS, or master queue)
Reserved for the operating system
Process priority number in master queue
Reserved for the operating system
Command Definitions
GETPROCINFO
Parameters
pin
16-bit signed integer by value (required)
Passes the PIN of the process that the returned message pertains to. If
requesting a parent process, set pin to zero. If requesting a child process, set
pin to the process identication number (PIN) of that process.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The process is already being terminated.
Request denied. An illegal PIN was specied.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-285
GETUSERMODE
NM and CM callable.
Dynamically returns a program to nonprivileged mode.
Syntax
GETUSERMODE;
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The program was in privileged mode at the time of the
intrinsic call.
Request granted. The program was in nonprivileged mode at the time of the
intrinsic call.
Not returned.
Related Information
Intrinsics
Commands
Manuals
4-286
None
None
None
Command Definitions
HP32208
HP32208
CM callable only.
Returns the current VUF (version, update, x level) of KSAM/3000.
Syntax
D
version:=HP32208
Functional Return
version
32-bit signed integer (assigned functional return)
Returns the VUF in the following format:
Bits
Value/Meaning
0:8
8:8
16:16
Version (ASCII format)
Update (binary format)
Fix level (binary format)
Operation Notes
This intrinsic is for use with KSAM les only.
Related Information
Intrinsics
Commands
Manuals
None
None
Using KSAM XL (32650-90168)
Command Definitions
4-287
HPACDINFO
Lists security information from the access control denition (ACD) of a specied le or device.
Syntax
I32
IV
*
HPACDINFO(status,itemnum1,item1
IV
*
[,itemnum2,item2][,...]);
A maximum of four itemnum2/item2 pairs can be specied. The last specied
itemnum2/item2 pair takes precedence over all identical itemnum2/item2
pairs specied. Any conict produces a warning message.
Note
Parameters
status
32-bit signed integer by reference (required)
Returns the status of the HPACDINFO call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
itemnum1
Bits (16:16) comprise status.subsys . The value represents the subsystem that
sets the status information. The subsystem identier for HPACDINFO is 246.
integer by value (required)
item1
Passes the number indicating the item . Refer to Table 4-11.
Type varies (required)
Passes the le or device identication information as specied in itemnum .
Refer to Table 4-11.
4-288
Command Definitions
HPACDINFO
itemnum2
integer by value (optional)
item2
Passes the number indicating the item2 . Refer to Table 4-12.
Type varies (optional)
Returns the variable information as specied in itemnum2 . Refer to
Table 4-12.
Command Definitions
4-289
HPACDINFO
Table 4-11. HPACDINFO Itemnum1/Item1 Values
Itemnum Mnemonic
Item Description
The following constants have been dened for a le or device request:
1
BA
Species the target le name. The item1 value specied must be a byte array of
1 to 35 characters (for MPE lenames), word aligned. Note that no wildcard
characters are allowed, a lockword can be included, and the le name specied
does not need to be fully qualied and can be specied using an MPE or HFS
name syntax. HFS pathnames must begin with a dot (.) or slash (/) character
and cannot exceed 1024 characters including the dot or slash. MPE lenames <
35 characters must be terminated with a null character or a carriage return.
3
UDS
Species the unique le identier (UFID). The item1 value specied must be a
20-byte structure, which can be obtained from the le system through the
HPFOPEN , FLABELINFO, or FFILEINFO intrinsics.
4
I
Species the le identier of a previously opened le. The item1 value specied
must be a 16-bit integer value.
6
I
Species the logical device number (ldev). The item1 value specied must be a
16-bit integer value.
7
BA
Species the name of a specic device. The item1 value specied must be a 1 to
8 character byte array.
1
BA
Species the target le name. The item1 value specied must be a byte array of
1 to 35 characters (for MPE lenames), word aligned. Note that no wildcard
characters are allowed, a lockword can be included, and the le name specied
does not need to be fully qualied and can be specied using an MPE or HFS
name syntax. HFS pathnames must begin with a dot (.) or slash (/) character
and cannot exceed 1024 characters including the dot or slash. MPE lenames <
35 characters must be terminated with a null character or a carriage return.
3
UDS
Species the unique le identier (UFID). The item1 value specied must be a
20-byte structure, which can be obtained from the le system through the
HPFOPEN , FLABELINFO, or FFILEINFO intrinsics.
4
I
Species the le identier of a previously opened le or directory. The item1
value specied must be a 16-bit integer value.
6
I
Species the logical device number (ldev). The item1 value specied must be a
16-bit integer value.
7
BA
Species the name of a specic device. The item1 value specied must be a 1 to
8 character byte array.
15
BA
Species the target lename. The item1 value specied must be a byte array of
< 1024 characters long inluding the terminating carriage return, blank, or null
character.
4-290
Command Definitions
HPACDINFO
Table 4-12. HPACDINFO Itemnum2/Item2 Values
Itemnum Mnemonic
Item Description
Security information that is not user-dependent can be requested using the following
itemnum2/item2 pairs:
20
A
Returns a unique identier representing the current version of the ACD.
Currently the version number is 5. The item2 value returned is a 16-bit integer.
21
I
Returns the number of ACD entries located in the target le ACD. The item2
value returned is a 16-bit integer.
22
BA
Returns a unique identier representing the rst user specied in the ACD. The
item value returned is a 1 to 18 character byte array.
Command Definitions
4-291
HPACDINFO
Table 4-12. HPACDINFO Itemnum2/Item2 Values (continued)
Itemnum Mnemonic
Item Description
Security information that is user-dependent can be requested using the following itemnum2/item2
pairs:
30
BA
Species the user whose ACD information is to be returned. The item2 value
specied must be an 18-character byte array, word aligned. If it is <18
characters, it must be terminated with a null character or a carriage return. This
entry is required for subsequent user-dependent requests.
31
BA
Returns ACD modes in ASCII format. The item2 value returned is a
25-character byte array.
32
I
Returns ACD modes as a bit mask. The item2 value returned is a 16-bit integer
whose bits have the following meaning:
r (0:1) - READ
w (1:1) - WRITE
x (2:1) - EXECUTE
a (3:1) - APPEND
l (4:1) - LOCK
z (8:1) - Permission to read
rd (11.1) td (12.1) cd (13.1) dd (14.1) n (15:1) - No access
33
BA
Returns ACD modes in ASCII format as access is granted the particular user.
The item2 value returned is a 25-character byte array. All wildcards are matched
from the user specication. The access granted the user in the selected ACD pair
can be greater than the access specied in the ACD pair if the user has AM or
SM capability.
34
I
Returns ACD modes as a bit mask of all accesses granted the particular user. The
item2 value returned is a 16-bit integer whose bits have the following meanings:
r (0:1) - READ
w (1:1) - WRITE
x (2:1) - EXECUTE
a (3:1) - APPEND
l (4:1) - LOCK
z (8:1) - Permission to read
rd (11.1) td (12.1) cd (13.1) dd (14.1) n (15:1) - No access
All wildcards are matched from the user specication. The access granted the
user in the selected ACD pair can be greater than the access specied in the
ACD pair if the user has AM or SM capability.
35
4-292
BA
Returns the next user in the ACD. The item2 value returned is a 1 to 18
character byte array.
Command Definitions
HPACDINFO
Operation Notes
The HPACDINFO intrinsic lists the requested security attributes of a specied le or device.
Three types of itemnum/item pair descriptors can be used to dene supplied input or to
specify returned ACD information. Such descriptors identify the le or device and request
nonuser-dependent and user-dependent data.
Related Information
Intrinsics
Commands
Manuals
HPACDPUT, HPFOPEN
LISTF, LISTFILE, SHOWDEV
MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003 and
32650-90364), System Startup, Conguration, and Shutdown Reference Manual
(32650-90042), MPE/iX Utilities Manual (32650-90081), and Controlling
System Activity (32650-90155)
Command Definitions
4-293
HPACDPUT
Manipulates security information in the access control denition (ACD) of a specied le or
device.
Syntax
I32
IV
*
IV
*
HPACDPUT(status,itemnum1,item1,itemnum2,item2);
Parameters
status
32-bit signed integer by reference (required)
Returns the status of the HPACDPUT call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
itemnum1
Bits (16:16) comprise status.subsys . The value represents the subsystem that
sets the status information. The subsystem identier for HPACDPUT is 246.
integer by value (required)
item1
Passes an identier code dening the accompanying paired input (item1).
The values for itemnum1 are described in the item1 parameter description.
Refer to Table 4-13.
Type varies by reference (required)
itemnum2
Passes the le or device identication information. The le or device identier
must be specied using one of the following predened itemnum1/item1 pairs.
Refer to Table 4-13.
Integer by value (required)
4-294
Passes the function code dening the accompanying paired input (item2).
The values for itemnum2 are described in the item2 parameter description.
Refer to Table 4-14.
Command Definitions
HPACDPUT
item2
Type varies by reference (required)
Passes the information to be used to manipulate the ACD of the specied le
or device.
Functionality requests can be made using one of the
predeneditemnum2/item2 pairs. Refer to Table 4-14.
Table 4-13. HPACDPUT Itemnum1/Item1 Values
Itemnum Mnemonic
1
BA
Item Description
Species the target le name. The item1 value specied must be a byte array of
1 to 35 characters, word aligned.
No wildcard characters are allowed, a lockword can be included, the le name
specied does not need to be fully qualied and can be specied using an MPE or
HFS name syntax. HFS pathnames must begin with a dot (.) or slash (/)
character and cannot exceed 1024 characters including the dot or slash. MPE
lenames < 35 characters must be terminated with a null character or a carriage
return.
2
BA
Species the target le name. The item1 value specied must be a byte array of
1 to 35 characters, word aligned.
Wildcard characters are allowed, a lockword can be included, the le name
specied does not need to be fully qualied, and a le name < 35 characters must
be terminated with a null character or a carriage return.
3
UDS
Species the unique le identier (UFID). The item1 value specied must be a
20-byte structure, which can be obtained from the le system through the
HPFOPEN , FLABELINFO, or FFILEINFO intrinsics.
4
I
Species the le number of a previously opened le. The item1 value specied
must be a 16-bit integer value.
5
N/A
Species all devices congured on the system. An item1 value is not required
with the option.
6
I
Species the logical device number (ldev). The item1 value specied must be a
16-bit integer value.
7
BA
Species the name of a specic device. The item1 value specied must be a 1 to
8 character byte array.
8
BA
Species the name of a specic device class. The item1 value specied must be a
1 to 8 character byte array.
15
BA
Species the target lename. The item1 value specied must be a byte array of
< 1024 characters long, including the terminating carriage return, blank, or null
character.
Command Definitions
4-295
HPACDPUT
Table 4-14. HPACDPUT Itemnum2/Item2 Values
Itemnum Mnemonic
Item Description
20
BA
Create a new ACD. The item2 value specied must be a 1 to 279 character byte
array.
21
BA
Add ACD pairs. The item2 value specied must be a 1 to 279 character byte
array.
22
BA
Replace ACD pairs. The item2 value specied must be a 1 to 279 character byte
array.
23
BA
Delete ACD pairs. The item2 value specied must be a 1 to 279 character byte
array.
24
N/A
Delete an ACD. An item2 value is not required with this option.
25
BA
Create a new ACD. The item2 value specied must be specied using an MPE
or HFS name syntax. HFS pathnames must begin with a dot (.) or slash (/)
character and cannot exceed 1024 characters, including the dot or slash. MPE
lenames < 35 characters must be terminated with a null character or a carriage
return.
26
BA
Copy an ACD from a specied le. The item2 value specied must be specied
using an MPE or HFS name syntax. HFS pathnames must begin with a dot (.)
or slash (/) character and cannot exceed 1024 characters, including the dot or
slash. MPE lenames < 35 characters must be terminated with a null character
or a carriage return.
27
UDS
Copy an ACD from the specied unique le identier (UFID). The item2 value
specied must be a 20-byte structure containing the UFID obtained from the le
system through the FLABELINFO and FFILEINFO intrinsics.
28
I
Copy an ACD from a previously opened le number. The item2 value specied
must be a 16-bit integer containing the lenum of the le containing the ACD to
be copied.
29
I
Copy an ACD from the specied logical device number (ldev). The item2 value
specied must be a 16-bit integer value.
30
BA
Copy an ACD from the specied device name. The item2 value specied must
be a 1 to 8 character byte array.
31
BA
Add ACD pairs. The item2 value specied must be specied using an MPE or
HFS name syntax. HFS pathnames must begin with a dot (.) or slash (/)
character and cannot exceed 1024 characters, including the dot or slash. MPE
lenames < 35 characters must be terminated with a null character or a carriage
return.
32
BA
Replace ACD pairs. The item2 value specied must be specied using an MPE
or HFS name syntax. HFS pathnames must begin with a dot (.) or slash (/)
character and cannot exceed 1024 characters, including the dot or slash. MPE
lenames < 35 characters must be terminated with a null character or a carriage
return.
33
BA
Delete ACD pairs.The item2 value specied must be specied using an MPE or
HFS name syntax. HFS pathnames must begin with a dot (.) or slash (/)
character and cannot exceed 1024 characters, including the dot or slash. MPE
lenames < 35 characters must be terminated with a null character or a carriage
return.
4-296
50
Command Definitions
I
File class indicating the maximum access to be calculated and assigned in the
class mask. The item2 value specied must be a a 32-bit interger.
HPACDPUT
Operation Notes
The HPACDPUT intrinsic allows programmatic adjustment, creation, and deletion of ACDs and
their security provisions. The intrinsic is used to create, copy, and delete an ACD and to add,
replace, modify, and delete pairs within an ACD.
Related Information
Intrinsics
Commands
Manuals
HPACDINFO, HPFOPEN
ALTSEC, COPY, PASSWORD, RELEASE, SECURE, STORE, RESTORE
MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003 and
32650-90364), System Startup, Conguration, and Shutdown Reference Manual
(32650-90042), MPE/iX Utilities Manual (32650-90081), and Controlling
System Activity (32650-90155)
Command Definitions
4-297
HPCICOMMAND
NM callable only.
Executes a command programmatically.
Syntax
CA
I16
I16
I16V
HPCICOMMAND( cmdimage,cmderror,parmnum,msglevel);
Parameters
cmdimage
cmderror
character array (required)
Passes an ASCII string of <=279 characters consisting of a command and
parameters, terminated by a carriage return. The carriage return character
(%15) must be the last character of the command string. Do not include a
prompt character in this string.
16-bit signed integer by reference (required)
Returns any error code set by the last executed command. When the CI
displays multiple errors for a single command, cmderr contains only the last
error number displayed.
If cmderror is zero, no error occurred.
If cmderror is negative, a warning was detected.
This is the same error that would be returned by the command interpreter if
cmdimage were executed interactively or in batch. The error message can be
found in message set two of CATALOG.PUB.SYS.
parmnum
Remote commands executed through the COMMAND or HPCICOMMAND intrinsics
may not return a meaningful error status.
16-bit signed integer by reference (optional)
Returns a number indicating the error:
If parmnum is positive, it is a le system error number and cmderror is
non-zero.
If parmnum is negative, it is the column number where the error occurred
and cmderror is non-zero. (The command interpreter (CI) prints a caret
there.)
If parmnum is zero, then no additional error-related data is available.
4-298
Command Definitions
HPCICOMMAND
Note
Check the cmderror parameter to verify ifcmdimage succeeded. The
parmnum may provide additional information.
msglevel
16-bit signed integer by value (optional)
Passes one of the following values, indicating how to handle error and warning
messages:
Value
0
1
2
Meaning
All error/warning messages will be printed to $STDLIST
(Default)
All CI error messages will be printed to $STDLIST; warning
messages will be suppressed
No error/warning messages will be printed to $STDLIST.
If a value other than 0, 1, or 2 is specied, msglevel defaults to 0 and CIWARN 9007 (Invalid
message level - expected 0, 1, 2) is sent to $STDLIST.
HPCICOMMAND prints a caret if the CI does, when given the same
parameter and msglevel <2.
cmdimage
Operation Notes
The HPCICOMMAND intrinsic allows the execution of UDCs and command les. RUN and other
process creation commands are allowed if you or the program calling HPCICOMMAND have
process handling (PH) capability.
The cmdimage parameter can contain any MPE/iX command except the following:
ABORT
BYE
CHGROUP
DATA
DISMOUNT
DO
EOD
EOJ
EXIT
HELLO
JOB
LISTREDO
MOUNT
MRJE
NRJE
REDO
RESUME
RJE
SETCATALOG
VSUSER
To control the error message display, use the msglevel parameter.
Related Information
Intrinsics
Commands
Manuals
COMMAND
None
Command Interpreter Access and Variables Programmer's Guide
(32650-90011) and MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364)
Command Definitions
4-299
HPCIDELETEVAR
NM callable only.
Removes a valid variable name from the session-level variable table.
Syntax
CA
I32
HPCIDELETEVAR(varname,status);
Parameters
varname
character array (required)
status
Passes the name of a session-level variable whose value is to be retrieved.
The name must begin with either an alphabetic character or the underscore
character. It must consist of alphanumeric or underscore characters. The
name is delimited by a nonalphanumeric, nonunderscore character, and can be
up to 255 characters long. The name is not case-sensitive.
32-bit signed integer by reference (optional)
Returns the status of the HPCIDELETEVAR call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that sets the status information. The subsystem
identier for HPCIDELETEVAR is 166.
Related Information
Intrinsics
Commands
Manuals
4-300
HPCIPUTVAR, HPCIGETVAR
SETVAR, DELETEVAR, SHOWVAR
Command Interpreter Access and Variables Programmer's Guide
(32650-90011) and MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364)
Command Definitions
HPCIGETVAR
HPCIGETVAR
NM callable only.
Retrieves a valid variable name from the session-level variable table and returns the current
value and/or attributes.
Syntax
CA
I32
U32V
*
HPCIGETVAR( varname,status[,itemnum,item] [...])
Note
You can specify up to six itemnum /item pairs.
Parameters
varname
character array (required)
status
Passes the name of a session-level variable whose value is to be retrieved.
The name must begin with either an alphabetic character or the underscore
character. It must consist of alphanumeric or underscore characters. The
name is delimited by a nonalphanumeric, nonunderscore character, and can be
up to 255 characters long. The name is not case-sensitive.
32-bit signed integer by reference (optional)
Returns the status of the HPCIGETVAR call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represents the subsystem that
set the status information. The subsystem identier for HPCIGETVAR is 166.
Command Definitions
4-301
HPCIGETVAR
itemnum
32-bit unsigned integer by value (optional)
item
Passes a number indicating the item , refer to Table 4-15.
type varies (optional)
Returns variable information as specied in itemnum , refer to Table 4-15.
Note
4-302
If the type of variable is unknown, pass the maximum number of
itemnum,item pairs (6) and check itemnum 13 (variable type) to determine
which item holds the variable's value.
Command Definitions
HPCIGETVAR
Table 4-15. HPCIGETVAR Itemnum/Item Values
Itemnum Mnemonic
Itemnum/item pair ignored
0
1
Item Description
I32
Integer value of variable (output):
0 if variable is not an integer.
Default: No value returned
2
CA
String value of variable (output):
An ASCII 0 is returned if the value of the variable is not a string.
Default: No value returned
3
I32
Boolean value of variable (output):
1 for a true value, 0 for a false value, 0 if variable is not a boolean.
Default: No value returned
10
I32
Length of array passed to hold variable's string value (input):
If a length is passed and an array is not, an error occurs.
Default: 255
11
I32
Actual length (in bytes) of variable's string value (output)
Default: No value returned
12
I32
Recursion used (input):
Nonzero if the variable is to be recursively dereferenced; zero if the variable
should not be recursively dereferenced (that is, it should retain its level one
value).
Default: 1 (nonzero)
13
I32
Type of variable (varname, if found) (output) :
The variable found returns the following:
1
Integer
2
String
3
Boolean
Default: No value returned
Note
For itemnum =12, recursively dereferenced variables are always returned as
string values.
Command Definitions
4-303
HPCIGETVAR
Related Information
Intrinsics
Commands
Manuals
4-304
HPCIPUTVAR, HPCIDELETEVAR
DELETEVAR, SETVAR, SHOWVAR
Command Interpreter Access and Variables Programmer's Guide
(32650-90011) and MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364)
Command Definitions
HPCIPUTVAR
HPCIPUTVAR
NM callable only.
Sets the value of a session-level variable.
Syntax
CA
I32
U32V
*
HPCIPUTVAR( varname,status[,itemnum,item] [...])
Note
Up to three itemnum/item pairs can be specied.
Parameters
varname
character array (required)
Passes the name of a session-level variable for which the value needs to be set.
This name must begin with either an alphabetic character or the underscore
character and consists of alphanumeric or underscore characters. The name is
delimited by a nonalphanumeric, nonunderscore character, and must be <=
255 characters long. The name is not case-sensitive.
Note
It is not a good practice to dene CI variables with the same names as JCW's
(job control words). Dening CI variables with the same names as JCW's may
cause unpredictable results.
status
32-bit signed integer by reference (required)
Returns the status of the HPCIPUTVAR call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represents the subsystem that
set the status information. The subsystem identier for HPCIPUTVAR is 166.
Command Definitions
4-305
HPCIPUTVAR
itemnum
32-bit unsigned integer by value (optional)
item
Passes an item number indicating the item . Refer to Table 4-16.
type varies by reference (optional)
Passes the variable information specied in itemnum . Refer to Table 4-16.
Table 4-16. HPCIPUTVAR Itemnum/Item Values
Itemnun Mnemonic
Itemnum/item pair ignored
0
1
Item Description
I32
Integer value assigned to specied variable name (input):
No other pairs are needed and, if specied, will cause an error. Default: Not
considered an integer value.
2
CA
String value assigned to specied variable name (input):
Default: Not a string variables.
Note: Requires itemnum 11. Itemnum 14 may be used with strings to set the
type and value of varname.
3
I32
The Boolean value to be assigned to the specied variable name (input).
Nonzero for a true value, zero for a false value.
Default: Not a boolean variable.
11
I32V
Actual length of value string assigned to variable name (input):
Itemnum /item pair 11 must be passed whenever itemnum 2 is passed.
14
I32
String interpretation (strings only; may be used only with itemnum =2) (input).
If you specify itemnum =14, the value of its corresponding item denes the
type-representation (and the value) of varname based upon an interpretation of
the item paired with itenum =2. Refer to \Itemnum 14".
Default: 0 (zero).
Itemnum 14
Given the (Pascal) code fragment
...
my_var := 'TESTVAR ';
var_value := 'Hello world';
val_len := 11;
item := 0; { default }
...
HPCIPUTVAR(my_var, status, 2, var_value,
11, val_len, 14, item)
The value of item will set the type (and value) of my var based upon an interpretation of
var value :
4-306
Command Definitions
HPCIPUTVAR
HPCIPUTVAR itemnum
14 with
item
Value Value of var value
of item
Type/Value of my var
=0
\TRUE"
Boolean (TRUE)
\FALSE"
Boolean (FALSE)
\123"
Integer (123)
\other chars"
String (\other chars")
\TRUE"
String (\TRUE")
\FALSE"
String (\FALSE")
\123"
String (\123")
\other chars"
String (\other chars")
<>0
values
Operation Notes
Allows the value of a session-level variable to be set. The name must be a valid MPE/iX
variable name. The variable's value can be either a 32-bit signed integer, an array of
characters, or a boolean (TRUE/FALSE).
Related Information
Intrinsics
Commands
Manuals
HPCIGETVAR, HPCIDELETEVAR
SETVAR, DELETEVAR, SHOWVAR
Command Interpreter Access and Variables Programmer's Guide
(32650-90011) and MPE/iX Commands Reference Manual Volumes 1 and 2
(32650-90003 and 32650-90364)
Command Definitions
4-307
HPDEBUG
NM callable only.
Enters the system debugger and optionally executes a dened set of system debug commands.
Syntax
I32 CA
I32V
*
HPDEBUG(status,cmdstr[,itemnum,item][...]);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPDEBUG call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
cmdstr
Bits (6:16) comprise status.subsys . The value represents the subsystem that
sets the status information. The subsystem identier for HPDEBUG is 165.
character array (optional)
Passes an array of <=1024 characters containing the system debugger
commands. The rst character in the buer is recognized as the delimiter.
The last character in the command string must be immediately followed by
that same delimiter.
This command string is executed when the system debugger is called:
For processes in jobs, process execution is resumed when the command
string is exhausted.
For processes in sessions, control remains in the debugger unless cmdstr
contains a CONTINUE command.
4-308
Command Definitions
HPDEBUG
itemnum
32-bit signed integer by value (optional)
item
Passes an item number indicating the item , refer to Table 4-17.
type varies by value (optional)
Passes the information specied in itemnum , refer to Table 4-17.
Table 4-17. HPDEBUG Itemnum/Item Values
Itemnum Mnemonic
1
I32
Item Description
Output le number:
Passes an opened le number where all output generated by Debug is sent. It
must be an ASCII le with write access. The value 1 is valid and species that
$STDLIST is used.
Default: Terminal LDEV for sessions and $STDLIST for jobs.
2
I32
Welcome banner ag:
Passes a value indicating whether the Debug welcome banner is printed or not. A
value of 0 indicates do not print the welcome banner. Any other value causes the
welcome banner to be displayed.
Default: Print welcome banner (1)
Operation Notes
The HPDEBUG intrinsic calls the system debugger with an optional character array containing
Debug commands. This option distinguishes HPDEBUG from the DEBUG intrinsic. If the
command list is dened, the debugger pushes the commands onto its command stack and
executes them. If no command in the command string causes control to be returned to the
calling procedure (for example, a CONTINUE command), the user is left in the debugger as
long as the process is being run from a session environment. Processes run from a job are not
allowed to stop in the system debugger. If the command string does cause control to return to
the calling procedure, any remaining commands are left pending on the debugger's command
stack to be executed the next time the debugger is called.
Related Information
Intrinsics
Commands
Manuals
DEBUG, HPSETDUMP, STACKDUMP
DEBUG
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
4-309
HPDEVCONTROL
NM callable only.
Provides access to specied peripheral functionality without the device being opened.
Allows access to device utilities; not for general control (for example, reading or writing).
Nonshareable device (ND) capability is required.
Syntax
I32
CA
I32
I32
HPDEVCONTROL(status,ldev,itemnum,item);
Parameters
status
32-bit integer (required)
Returns the status of the HPDEVCONTROL call. If no errors or warnings
are encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
ldev
Bits (16:16) comprise status.subsys . The value represents the subsystem
that sets the status information. There is no specic subsystem identier for
HPDEVCONTROL.
character array (required)
Passes the LDEV number of the device to be accessed. This parameter is a
200-character packed array.
Note
This parameter must be delimited with a printable, non-numeric character
and must be zero left-lled:
"00000007" or
a00000007a
Whatever delimiter begins the parameter must also end the parameter. The
delimiter itself must not appear within the parameter.
a0000a007a will cause an error because a appears within the parameter.
Note
4-310
The LDEV parameter must be dened as 200 characters in the calling
program. However, because logical device numbers are currently limited in size
to 10 bytes only the leftmost 10 bytes of the array is used. For this reason, the
ldev should be loaded into the leftmost 10 bytes of the 200-character array
before the call is made.
Command Definitions
HPDEVCONTROL
itemnum
It also may be important to understand that the system converts this
parameter to a pointer before passing it to the intrinsic. It should not be
coded as a pointer in the calling program, however.
32-bit integer (required)
item
Species which operation is to be performed (refer to Table 4-18).
32-bit integer (required)
Table 4-18. HPDEVCONTROL Itemnum/Item Values
Itemnum Mnemonic
100
I32
Item Description
Load Media:
Attempts to load the media (tape devices only).
101
I32
Online:
Programmatically places the peripheral online (tape devices only).
This intrinsic is not supported for the following devices: 7974, 7976 and 7978A. If a call is
made against one of these devices an error is returned. Only item number 100 is supported for
the 7978B.
Note
A call with an item number 100 (load) to a device which is already loaded
is acceptable (produces no harmful result). However a tape device would go
oine (only an HPIB DAT drive would not go oine). It is recommended
that this intrinsic be called with item 100 followed by 101 whenever it is used
for a tape device.
Related Information
Intrinsics
Commands
Manuals
None
None
None
Command Definitions
4-311
HPDEVCREATE
Provides an application interface to create a streams, fo, and device link le.
Syntax
CA
I32V
I32V
HPDEVCREATE (pathname,path syntax,path length,status,
I32V
[,itemnum,item] [ . . . ]);
Parameters
pathname
32-bit pointer to a packed array of characters (required)
path syntax
The name of the device le to be created. If the path length does not indicate
the length of the pathname, the device le name is assumed to be terminated
with a null.
32-bit integer by value (optional)
Indicates the syntax of the name in the pathname parameter. The valid values
are:
0
MPE Escaped Syntax
1
MPE Only Syntax
2
POSIX Syntax
path length
A value other than those listed above results in an error. The default value is
0 (MPE escaped syntax). MPE escaped syntax allows a name to be expressed
in either MPE or POSIX syntax.
32-bit integer by value (optional)
Indicates the length of the name in the pathname parameter. A positive
value is taken as the exact length of the name, excluding any terminating
characters.
4-312
Command Definitions
HPDEVCREATE
If an invalid character is found in the pathname , an error is returned. Passing
a -1 value indicates that the length of the name is unknown. HPDEVCREATE
parses the name in the pathname parameter until it nds either a terminating
character, an invalid character, or the name is 1023 characters. Passing a
value of zero indicates a null or empty name will result in an error. Passing a
negative value other than -1 will result in an error.
status
Default is -1.
32-bit integer by reference (optional)
Returns an indication of the success or failure of the intrinsic call.
If no errors or warnings occur, status returns 32-bits of zero.
If errors or warnings occur, status is interpreted as two 16-bit elds:
Bits (0:16)
Comprise status.info. A negative value indicates an
error condition, and a positive value indicates a warning
condition.
Bits (16:16)
Comprise status.subsys. The value represents
the subsystem that sets the status information. For
HPDEVCREATE intrinsic, the subsystem is File System
(143).
keyword#
If the status parameter is not specied and an error occurs
during the processing of HPDEVCREATE call, the calling
process aborts.
32-bit integer by value (optional)
keyvalue#
Species a keyword value used in combination with the corresponding
keyvalue parameter. Species the type of device le options used to create a
device le. Up to 32 keyword/keyvalue pairs may be specied in a call to
HPDEVCREATE. The following table lists the dened keyword/keyvalue pairs.
Specifying a keyword other than those below will result in a error.
If duplicate keywords are specied in a call to HPDEVCREATE, the last
keyvalue is used, and a warning is returned to the caller.
If no keyword/keyvalue pairs are specied, an error is returned.
Type varies by reference (optional)
The keyvalue parameter is matched with its corresponding keyword to pass
information to HPDEVCREATE. If a keyword is specied and the keyvalue is not
present, an error will occur.
Command Definitions
4-313
HPDEVCREATE
Table 4-19. HPDEVCREATE Keywords/Keyvalues
Keyword Type
0
None
Description
End of option list.
There is no corresponding keyvalue. Terminates the keyword/keyvalue list and is
equivalent to not passing a keyword/keyvalue pair.
1
I32
Device File Category.
This option allows you to create one of several types of device les. The following
is a list of valid categories:
1
FIFO
Specifying this category creates a FIFO le. You can specify
the ACD option with this item number. Any other option will
result in an error.
2
STREAMS
Specifying this category creates a STREAMS le using the
attributes specied in the major number (item 3), minor
number (item 4), and the link name (item 5). If this category is
specied, then the major or minor number options are required.
3
DEVICE LINK
Specifying this category creates a device link le using the
LDEV number specied in item 2 (LDEV). If you specify this
category, then item 2 is required.
2
I32
LDEV
Specifying this option causes a logical symbolic link to a device created using the
LDEV numbet provided in the keyvalue parameter. This option is only valid
when the device le category 3 (device link) is specied. If other options are
specied, an error is returned.
3
I32
Major Number.
This option allows specications of device les in a traditional UNIX manner of
major and minor numbers. If the major number is specied, the minor number
option must also be specied, or an error is returned. The following major
numbers are valid:
1-254
Used to indicate a streams device le.
Specifying a major number value other than 1-254 will result
in an error.
4-314
Command Definitions
HPDEVCREATE
HPDEVCREATE Keywords/Keyvalues
Keyword Type
4
I32
Description
Minor Number.
This option is used in conjunction with option 3 to provide UNIX compatible
device specication. If the minor number is specied, the major number must be
specied, or an error is returned. The interpretation of the minor number is
dependent on the value of the major number. The minor number represents a
streams connection to a driver.
A minor number is valid in the range from 0 to 16777215 (represented by 24 bits).
5
CA
Link Name.
This option may be used with the major and minor number options (3 and 4)
when a streams device is being created. An error is returned if this option is
specied with any device le category other than STREAMS.
The maximum size of this option is 8 characters (from the NMMGR link screen).
A character placed in the rst element designates the delimiter used to search to
the end of the character array. For example:
%linkname% (% is the delimiter)
6
BA
Access Control Denition (ACD):
Passes a byte array dening the access control denition (ACD) to be attached to
the streams or FIFO le. The array has a length of 1 to 279 bytes. This option
expects a trailing carriage return character as a delimiter. For example:
(X:@.@;R,W:JOE.SYS;RACD:SUE.SMITH)<cr>
The <cr> is the carriage return character (13,0x0D).
An error is returned if this item is specied when creating a device link le.
Operation Notes
When creating a device link, you are creating a symbol to a device with its default
conguration parameters.
Related Information
Intrinsics
Commands
Manuals
None
None
None
Command Definitions
4-315
HPENBLTRAP
NM callable only.
Selectively enables or disables arithmetic traps.
Syntax
I32V
I32
HPENBLTRAP( mask,oldmask);
Parameters
mask
32-bit signed integer by value (required)
Passes a value indicating which arithmetic traps are enabled and which are
not:
If a bit is on (=1), the corresponding trap is enabled.
If a bit is o (=0), the corresponding trap is disabled.
The bits and their associated arithmetic errors are:
Bits
31:1
30:1
29:1
28:1
27:1
26:1
25:1
24:1
23:1
22:1
21:1
19:2
18:1
17:1
16:1
4-316
Command Definitions
Value/Meaning
3000 mode oating-point divide by zero
Integer divide by zero
3000 mode oating-point underow
3000 mode oating-point overow
Integer overow
3000 mode double-precision overow
3000 mode double-precision underow
3000 mode double-precision divide by zero
Decimal overow
Invalid ASCII digit
Invalid decimal digit
Reserved for the operating system
Decimal divide by zero
IEEE oating-point, inexact result
IEEE oating-point underow
HPENBLTRAP
Bits
Value/Meaning
15:1
14:1
13:1
12:1
11:1
10:1
IEEE oating-point overow
IEEE oating-point divide by zero
IEEE oating-point, invalid operation
Range errors
Software-detected NIL pointer reference
Software-detected misaligned result of pointer arithmetic or
error in conversion from long pointer to short pointer
Unimplemented condition traps
Paragraph stack overow
3000 mode packed decimal error
Reserved for MPE/iX
Assertion trap
9:1
8:1
7:1
1:7
0:1
Note
The following apply to various trap conditions represented in the mask
parameter:
Native mode supports two oating-point formats: IEEE and 3000 mode.
Both execute in native mode, but 3000 mode performs
HP 3000 type manipulations. Since it is possible to use both formats
during program execution, there are separate bits in the mask for
enabling/disabling traps of these formats.
Some error conditions specied are not strictly arithmetic traps (for
example, range errors, nil pointers, and paragraph stack overow). However,
many arithmetic traps are caught by reserved instructions that raise the
conditional traps. For this reason, all are enabled/disabled by HPENBLTRAP.
Some of the instructions that raise conditional traps are reserved to indicate
some of the above trap conditions. A nonreserved instruction is one not
generated by a compiler. If a nonreserved instruction causes a conditional
trap, this is reported as an unimplemented condition trap.
oldmask
32-bit signed integer by reference (required)
Returns the value of the previous mask to the program.
Command Definitions
4-317
HPENBLTRAP
Operation Notes
Allows selective enabling or disabling of arithmetic traps. It provides more exibility than the
ARITRAP intrinsic, which collectively enables or disables traps.
There is a dierence between arming and enabling traps:
Enabling a trap means that the occurrence of a trap condition is not ignored.
Arming a trap is required so that, on a trap condition, a user-written routine is invoked and
can take appropriate recovery actions.
The following list summarizes what can occur when an arithmetic trap condition arises:
If a trap is both enabled and armed, the user-written trap handler is invoked whenever a
trap condition occurs.
If a trap is enabled but not armed, one of two situations applies:
If a Pascal/XL TRY statement has been executed, control is passed to the recover block by
doing an escape.
If a Pascal/XL TRY statement has not been executed, an error message is output and the
process aborts.
If a trap is disabled, irrespective of whether it is armed, the trap is ignored, and execution
of the process continues without any interruption.
By default, all traps except IEEE oating-point exceptions are enabled, and
the system trap handler is armed. Many oating-point operations result in
an inexact result. Consequently, most compiler libraries doing oating-point
operations result in an inexact trap if the IEEE inexact result trap is enabled.
Note
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. All traps were originally disabled.
Request granted. At least one trap was originally enabled.
Not returned.
Related Information
Intrinsics
Commands
Manuals
4-318
None
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
HPERRDEPTH
HPERRDEPTH
NM callable only.
Returns the current depth of the process error stack.
Syntax
I32
I32
HPERRDEPTH( depth,status);
Parameters
depth
32-bit signed integer by reference (required)
status
Returns the current number of entries on the process error stack.
32-bit signed integer by reference (optional)
Returns the status of the HPERRDEPTH call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represents the subsystem that
set the status information. The subsystem identier for HPERRDEPTH is 187.
Default = NIL
Caution
If an error or warning is encountered and the status parameter was not
specied, HPERRDEPTH causes the calling process to abort.
Operation Notes
HPERRDEPTH can be used to check the depth of the error stack before using HPERRMSG.
Note
With the exception of HPERRMSG, HPERRREAD, and HPERRDEPTH, all intrinsics
that are called clear the process error stack.
If other intrinsics are called before or during the process of reading the error
stack, then the stack is cleared and the information it contained is lost.
Command Definitions
4-319
HPERRDEPTH
Related Information
Intrinsics
Commands
Manuals
4-320
HPERRMSG, HPERRREAD''
None
Getting System Information Programmer's Guide (32650-90018) and MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368)
Command Definitions
HPERRMSG
HPERRMSG
NM callable only.
Obtains or displays error messages from the system catalog.
Syntax
I32V
I32V
I16
I32V
HPERRMSG(displaycode,depth,errorproc,errornum,
CA
I16
I32
buer,buength,status);
Parameters
displaycode
32-bit signed integer by value (required)
Species the operation to be performed:
Value
1
2
3
4
5
6
Meaning
Dump the error stack to $STDLIST and display any errors that
are detected by HPERRMSG (returned in status ).
Display to $STDLIST the error message corresponding to the
value in errornum and display any errors that are detected by
HPERRMSG (returned in status ).
Obtain the error message corresponding to the value in
errornum and place it in the buer specied by buer .
Display to $STDLIST the number of stack errors specied in
depth and display any errors detected by HPERRMSG (returned
in status ).
Display to $STDLIST the error message corresponding to
errornum . Do not display any errors that are detected by
HPERRMSG (returned in status ), but save information in the
status parameter.
Obtain the subsystem/error identication number
corresponding to the error number in errornum , and place it in
the buer specied by buer .
Command Definitions
4-321
HPERRMSG
Value
7
8
depth
Meaning
Get messages for the number of stack errors specied in depth
and place them in the buer specied by buer . The contents
of buer contains the same information as if the user had
specied displaycode 4, including errors that are detected by
HPERRMSG. All messages are separated by carriage return/line
feed characters.
Dump the error stack to the buer specied by buer . The
result is the same as with displaycode 1, except that the
messages are placed in buer , separated by carriage return/line
feed characters.
32-bit signed integer by value (optional)
Species the number of error entries from the stack that are to be displayed.
A 1 (one) implies the last error entry made.
errorproc
Default = 0
16-bit signed integer (reserved)
Do not specify this parameter, but maintain parameter position.
errornum
Default = 0
32-bit signed integer by value (optional)
Passes a subsystem error identication number whose corresponding message
from the system catalog is to be displayed or returned. An errornum is
interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information.
buer
If not specied, defaults to 0.
character array (optional)
Species the buer where text from the system catalog error messages are to
be placed.
If not specied, defaults to NIL.
4-322
Command Definitions
HPERRMSG
buength
16-bit signed integer by reference (optional)
Passes the length of the buer input:
As an input parameter, the length of the buer where the error messages
are to be placed. If the resulting messages are longer than this length, they
are truncated. This procedure does not verify that the buer parameter has
enough storage to hold the number of bytes specied by buength . If there
is not enough storage, the caller's stack may be corrupted.
As an output parameter, the actual length (in bytes) of the messages that
were returned.
If buer is specied, buength must also be specied.
status
If not specied, defaults to NIL.
32-bit signed integer by reference (optional)
Returns the status of the HPERRMSG call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, errornum is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPERRMSG is 187.
If not specied, defaults to NIL.
Caution
If an error or warning is encountered and the status parameter was not
specied, HPERRMSG causes the calling process to abort.
Command Definitions
4-323
HPERRMSG
Operation Notes
Allows the user to obtain or display error messages from the system catalog by supplying the
corresponding error statuses. The caller can supply a status whose corresponding message
is to be displayed, or specify that the messages corresponding to one or more errors in the
process error stack be displayed. The caller can optionally provide a buer and ask that the
error messages be placed in that buer rather than be displayed to the user.
For errors that are displayed from the process error stack, any parameters that were pushed
with the errors are inserted into the corresponding messages. Also, when dumping the entire
stack, the user is warned if any entries on the process stack were overwritten. (This happens if
more than 16 entries were pushed onto the stack.) If any entries were overwritten, the oldest
entries are the ones lost.
With the exception of HPERRMSG, HPERRREAD, and HPERRDEPTH, all intrinsics
that are called clear the process error stack.
Note
If other intrinsics are called before or during the process of reading the error
stack, then the stack is cleared and the information it contained is lost.
The internal software which moves error codes onto the error stack is a
proprietary part of the MPE/iX operating system. Hewlett-Packard currently
provides no user-callable procedure to move error codes onto the error stack.
Note
Related Information
Intrinsics
Commands
Manuals
4-324
HPERRDEPTH, HPERRREAD
None
Getting System Information Programmer's Guide (32650-90018) and MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368)
Command Definitions
HPERRREAD
HPERRREAD
NM callable only.
Reads any specied error from the process stack.
Syntax
I32V I32
I32
I32
HPERRREAD(depth,errornum,procnum,status
Parameters
depth
32-bit signed integer by value (required)
errornum
Passes the index of the stack entry to read from. A 1 (one) implies the last
entry that was pushed. Specication of depth equal to that of the actual stack
depth implies the oldest entry on the stack. An error is returned if the value
of this parameter does not correspond to an error in the stack.
32-bit signed integer by reference (required)
Returns the error status that was read from the stack. This value is only valid
if status is zero.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition.
procnum
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information.
32-bit signed integer by reference (optional)
Do not specify this parameter. Instead, maintain the parameter position with
a comma. Always returns zero.
status
If not specied, defaults to NIL.
32-bit signed integer by reference (optional)
Returns the status of the HPERRREAD call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, errornum is interpreted as two 16-bit elds.
Command Definitions
4-325
HPERRREAD
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPERRREAD is 187.
If not specied, defaults to NIL.
Caution
If an error or warning is encountered and the status parameter was not
specied, HPERRREAD causes the calling process to abort.
Operation Notes
Allows the user to read any specied error from the process stack. The user species how far
down into the stack to read, and the corresponding error status is returned in errornum. If
any parameters were pushed onto the stack with the specied error, this intrinsic does not
return them. Refer to the HPERRMSG intrinsic for information on how to display errors with
their parameters.
With the exception of HPERRMSG, HPERRREAD, and HPERRDEPTH, all intrinsics
that are called clear the process error stack.
Note
If other intrinsics are called before or during the process of reading the error
stack, the stack is cleared, and the information it contained is lost.
The internal software which moves error codes onto the error stack is a
proprietary part of the MPE/iX operating system. Hewlett-Packard currently
provides no user-callable procedure to move error codes onto the error stack.
Note
Related Information
Intrinsics
Commands
Manuals
4-326
HPERRDEPTH, HPERRMSG
None
Getting System Information Programmer's Guide (32650-90018) and MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368)
Command Definitions
HPFDUPLICATE
HPFDUPLICATE
NM callable only.
Creates duplicate le descriptors for les opened for MULTI, SHARED, or EXCLUSIVE
access.
Syntax
I16
I32
I32V *
lenum:=HPFDUPLICATE(source,status,target);
Functional Return
lenum
16-bit signed integer (assigned functional return)
Returns the actual le number used to duplicate the source le. This
le number can be dierent than the le number requested in the target
parameter. If an error occurs during the duplication process, a -1 value is
returned.
Parameters
source
32-bit signed integer by value (required)
status
Species the le number to be duplicated. The le number must be a valid,
open le.
32-bit signed integer by reference (optional)
target
Returns the status of the HPFDUPLICATE call. If an error occurs and this
parameter was not specied, the functional return can be used to determine
the success or failure of the call.
32-bit signed integer by reference (optional)
Species the le number to be duplicated in the source parameter. If the le
number is already opened, the next highest available le number is used. The
value passed must be within the legal range of le numbers. The default value
for this parameter is zero (0).
Operation Notes
When a le descriptor is duplicated, the duplicate le descriptor shares the same data pointer
as the original le descriptor in the same way that le descriptors share the same data pointer
with MULTI access. This gives you the ability to perform operations on les that have not
been previously available. Specically, les that are opened for SHARED or EXCLUSIVE
access can now have their data pointers shared among multiple le descriptors, at the
discretion of the application that originally opens the le descriptor.
Command Definitions
4-327
HPFDUPLICATE
Related Information
Intrinsics
Commands
Manuals
4-328
FOPEN, HPFOPEN
None
None
Command Definitions
HPFIRSTLIBRARY
HPFIRSTLIBRARY
NM callable only.
Returns the le name of the rst executable library (XL) in the binding sequence of the
calling process.
Syntax
CA
I32 I32 CA
HPFIRSTLIBRARY(formaldesig,status,length,rstlib,
I32
I32
rstlib length, rstlib syntax);
Parameters
formaldesig
character array (required)
Returns the fully qualied MPE syntax le name of the rst XL in the
binding sequence of the calling process.
status
The formaldesig parameter must be at least 28 bytes in length in order
to contain the longest possible MPE syntax le name with delimiters. The
lockword is not returned. The rst and last characters of the returned value
are blanks that act as delimiters.
32-bit signed integer by reference (optional)
HPFIRSTLIBRARY returns a NM Loader error 128 when the rst library name
length
rstlib
cannot be represented using the syntax that the user species.
32-bit signed integer by reference (optional)
Returns the length of formaldesig parameter. The length includes the
surrounding delimiters.
character array (optional)
Returns the absolute pathname or fully qualied MPE syntax name of the
rst executable library in the binding sequence of the calling process.
rstlib length
The rstlib parameter contains the name with delimiters. The rst and last
characters of the returned value are blanks that act as delimiters.
32-bit signed integer by reference (optional)
On input, the rstlib length parameter species the maximum rstlib length
in bytes.
On output, the rstlib length parameter returns the actual length of rstlib .
The length includes the surrounding delimiters.
If rstlib length is incorrect when input, variables allocated near rstlib can
be overwritten, or an error could occur. If the rstlib length parameter is not
Command Definitions
4-329
HPFIRSTLIBRARY
specied, HPFIRSTLIBRARY determines if the rstlib parameter is long enough
to hold the rst library name to be returned.
Note that a value is not returned in rstlib length if the rstlib parameter is
not specied.
rstlib syntax 32-bit signed integer by reference (optional)
On input, the rstlib syntax parameter species the syntax that will be used
when HPFIRSTLIBRARY returns a name in the rstlib parameter.
On output, the rstlib syntax parameter returns the syntax that is actually
used. This is only useful when MPE-escaped syntax is specied on input and
the name can legally be either an MPE syntax name or an HFS syntax name.
Note that a value is not returned in rstlib syntax if the rstlib parameter is
not specied. The possible syntaxes are MPE-escaped syntax (0), MPE-only
syntax (1), and HFS syntax (2)/.
Default is MPE-only syntax.
Operation Notes
This intrinsic searches les in the binding sequence for a procedure, beginning with the rst
XL. The rst XL is the second le in the binding sequence (located immediately after the
program le).
Related Information
Intrinsics
Commands
Manuals
4-330
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
HPFOPEN
HPFOPEN
NM callable only.
Creates le objects and supports FIFO les.
Syntax
I32
I32
I32V *
HPFOPEN(lenum,status[,itemnum,item] [...]);
Note
Up to 41 itemnum /item pairs can be specied.
Parameters
lenum
32-bit signed integer by reference (required)
Returns a le descriptor for a FIFO le.
status
Can be used safely with all le system intrinsics that require a 16-bit le
number to be passed in the intrinsic call (for example, FREAD, FWRITE,
FCLOSE).
32-bit signed integer by reference (optional)
Returns the status of the HPFOPEN call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds:
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise.status.subsys . The value represents the subsystem that
set the status information. The subsystem identier for HPFOPEN is 143.
Caution
If an error or warning is encountered and the status parameter was not
specied, HPFOPEN causes the calling process to abort.
Command Definitions
4-331
HPFOPEN
itemnum
32-bit signed integer by value (optional)
item
Passes the item number. Refer to Table 4-20.
type varies by reference (optional)
Passes and/or returns the option indicated by the corresponding itemnum
parameter. Refer to Table 4-20.
Note
4-332
An itemnum takes precedence over any previously specied duplicate
itemnum . Any duplicated itemnum is agged as a warning.
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values
Itemnum Mnemonic
0
Item Description
End of option list:
There is no corresponding item . The absence of an itemnum after the last
itemnum ,item pair is equivalent to specifying this option.
2
CA
Formal designator:
Passes a formal le designator that is interpreted according to MPE-escaped
semantics (unless another syntax has been chosen via item 41). The le name
must be terminated by a nonalphanumeric character other than a period (.), a
slash (/), a hyphen (-), and an underscore ( ). Use of matched starting and
ending name delimiters (a quoted name) alleviates the need for a terminating
character other than the quote characters.
The le referred to by formaldesig can be either an MPE le (i.e., one that uses
MPE syntax) or it can follow HFS syntax. If formaldesig follows MPE syntax,
the le name can include password, group, and account specications. The le
name can backreference a le equation and optionally be preceded by an asterisk.
If formaldesig follows HFS syntax, the le name must start with either a dot (.)
or a slash (/).
The le referred to by formaldesig may reside either in an MPE group or in an
HFS directory. For les located in HFS directories, traverse directory entries
(TD) access is required to all directories specied in formaldesig . If there is no
TD access, HPFOPEN fails and a value of -180 is returned in the status.info
parameter. If you are using HPFOPEN to create a le or hierarchical directory and
you lack of create directory entry (CD) access, status .info will return a value of
-179.
If formaldesig is an escaped pathname:
you cannot reference remote les
it cannot express a name equivalent to lename :envid
you cannot use the device parameter (device =node #) to specify the remote
location of a device
If formaldesig is the name of a user-dened le, it can begin with an asterisk (*).
If formaldesig is the name of a system-dened le, it can begin with a dollar sign
($). When creating a KSAM le, formaldesig must be a unique le name, that is,
one not currently existing in the permanent le directory.
The formal le designator can contain command interpreter variables and
expressions that are evaluated before formaldesig is parsed and validated.
As the default, HPFOPEN creates a nameless le that can be read or written to,
but not saved. (The domain option of a nameless le must specify a new le
unless it is a device le.)
Command Definitions
4-333
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
2 cont'd
Item Description
The following are examples of valid formal le designators:
&file/lock.group.account:node.dest.level&
&filename&
&!myfile&
&!afile/![FINFO("!afile",33)]&
The following are examples of invalid formal le designators:
"filename.group (missing delimiter ("))
file.group" ( 'f' is used as delimiter, missing at end)
(ASC) It is recommended that this itemnum , item pair be used for asynchronous
devices.
When you use HPFOPEN to open a le, you may use either itemnum =2 or
itemnum =51; you cannot use both.
3
I32
Domain:
Passes a value indicating which le domain the system searches to locate the le.
A nameless disk le must always be a new le.
A device le (such as a tape drive, terminal, spooled printer or hot printer)
always resides in the system le domain (permanent le directory). Always
specify a device le as old or permanent.
The following values are valid:
0
The le is a new temporary le. It is not placed in a directory.
1
The le is a permanent le, found in the system le domain.
2
The le is a temporary le, found in the job le domain.
3
The le is an old (permanent or temporary) le. The job le domain is
searched rst. If the le is not found, the system le domain is searched.
4
The le is created, placed in the permanent le directory, and becomes a
permanent le.
Hierarchical directories must be created in the permanent le domain by
specifying the create le domain (4).
Default: 0
4-334
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
5
I32
Item Description
Designator:
Passes a value indicating a special le opening. Any of the following special les
can be specied with the itemnum =2. For example, a le name of $STDLIST
opens the standard list device. The following values are valid:
0
Allows all other options to specify the le.
1
The actual le designator is $STDLIST .
2
The actual le designator is $NEWPASS .
3
The actual le designator is $OLDPASS .
4
The actual le designator is $STDIN.
5
The actual le designator is $STDINX.
6
The actual le designator is $NULL.
Default: 0
For example, if MYFILE is passed in itemnum =2, then using itemnum =5 and
item =4 to equate it with $STDIN is equivalent to the le equation FILE
MYFILE=$STDIN.
This option is not equated with itemnum =2 if both of the following conditions
are true:
The itemnum =9 option allows le equations for the le opening.
An explicit or implicit FILE command equating the formal le designator to a
dierent actual le designator occurs in the job/session.
A leading * in a formal le designator passed by itemnum =2 overrides an
itemnum =9 option.
6
I32
Record format:
Passes a value indicating the internal record structure desired for the le. This
option is applicable only at le creation.
The following values are valid for records:
0
Fixed-length
1
Variable-length
2
Undened-length (no implied structure)
9
Byte stream
10
Hierarchical directory
Default: 0
Command Definitions
4-335
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
Byte stream record format may be specied only for standard disk les (itemnum
10 equal to 0). Hierarchical directory record format is the the default record
format when creatinng a directory (itemnum 10 equal to 9). Itemnum 10 equal
to 9 is the only record format which may be specied when creating a directory.
Hierarchical record format is only specied for the directory le type. Record
formats not implemented for the specied le type are ignored. Byte stream and
hierarchical directory record formats are supported only on disk devices.
6 cont'd
(ASC) This itemnum,item pair is ignored for les opened on a terminal; records
of les on terminals are of undened length. If the le is to be redirected to tape
or disk, set the value to 0 (xed-length).
FIFO le must be created with the byte streams (9) record format.
7
I32
Carriage-control:
Passes a value indicating whether or not a carriage-control directive is supplied in
the calling sequence of each FWRITE call that writes records onto the le. This
option is applicable only at le creation.
The following values are valid:
0
No carriage-control directive expected
1
Carriage-control directive expected
Default: 0
Carriage-control is dened only for ASCII les. This option and itemnum =53 are
exclusive, and attempts to open new les with both binary and carriage-control
directives result in an access violation.
A carriage-control character passed through the control parameter of FWRITE is
recognized for les with carriage-control specied in HPFOPEN/FOPEN . Embedded
control characters are treated as data on les where no carriage-control is
specied, and spacing is not invoked for the le. Specify spacing action on les
where carriage-control has been specied by either embedding the control in the
record, indicated with a control parameter in the call to FWRITE, or by sending
the control code directly through the control parameter of FWRITE.
If a carriage-control character is sent to a le where the control cannot be
executed directly (for example, line spacing characters sent to a disk or tape le),
the control character is embedded as the rst byte of the record. Therefore, the
rst byte of each record in a disk le having carriage-control characters enabled
contains control information. If carriage-control characters are sent to other
types of les, the control is transmitted to the driver.
Control codes %400 through %403 are remapped to %100 through %103, so that
they t into one byte and can be embedded. Records written to the line printer
with control codes %400 through %403 should contain only control information.
Records written with control codes %400 through %403 and no data (count=0,
or embedded control and count=1) does not cause physical I/O.
4-336
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
7 cont'd
Item Description
For computing record size, the le system considers carriage-control information
as part of the data record. Therefore, specifying the carriage-control option adds
one byte to the record size when the le is originally created. For example, a
specication of REC=-132,1,F,ASCII;CCTL results in a recsize of 133 bytes.
Generally, the entire record can be read. Refer to the table listing the item values
returned by the FFILEINFO intrinsic. However, on writes to les where
carriage-control characters are specied, the data transferred is limited to
recsize -1 unless a control of one is passed, indicating the data record is prexed
with embedded carriage-control characters.
The value of this itemnum is ignored when a byte stream or hierarchical
directory is created. Byte stream les and hierarchical directories are created
without carriage control (NOCCTL).
8
CA
Enable tape label:
Passes the tape label name of a labeled tape. The name must follow the ANSI
standards for tape label names. The name consists of <=6 printable characters
that identify the volume. In a multivolume set, only the rst tape label can be
specied.
Default: a null tape label
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%volid% (% is the delimiter, volid is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
(ASC) Not used for asynchronous devices.
9
I32
Disallow le equation:
Passes a value indicating whether or not le equations are allowed. A leading *
in a formal le designator overrides the setting to disallow le equations.
The following values are valid:
0
Allow le equations to override programmatic or system-dened le
specications.
1
Disallow le equations from overriding programmatic or system-dened le
specications.
File equations can be enabled for escaped pathnames expressed using
MPE-escaped name semantics or names expressed using POSIX name semantics,
but a matching le equation is not found since the le designator on the left side
of a le equation can only be expressed using MPE-only syntax.
Default: 0
Command Definitions
4-337
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
10
I32
Item Description
File type:
Passes a value indicating the internal record structure used to access records in
the le. If the le is old, this option is ignored. Specifying an itemnum =5 value
other than zero overrides this option. This option is applicable only at le
creation.
The following values are valid:
0
Standard (STD) le
1
KSAM/3000 le
2
Relative I/O (RIO) le
3
KSAM XL le
5
NM spoolle
4
Circular (CIR) le
6
Message (MSG) le
9
Directory
Default: 0
Hierarchical directories must be created in the permanent le domain.
KSAM/3000 (1), RIO (2) and CIR (4) le types may only be created using
names belonging to the MPE name space.
(ASC) Set the value to 0 for asynchronous devices.
11
I32
Access type:
Passes a value indicating the type of access intended for the le. This option
restricts/allows usage of the le system intrinsics.
The following values are valid:
4-338
0
Read access only, if the le's security provisions allow read access. FWRITE,
FUPDATE , and FWRITEDIR intrinsic calls cannot reference this le. The
end-of-le (EOF) is not changed; the record pointer starts at zero. (Default)
1
Write access only, if the le's security provisions allow write access. Any
data written in the le prior to the current HPFOPEN request is deleted.
FREAD, FREADSEEK, FUPDATE , and FREADDIR intrinsic calls cannot reference
this le. The EOF is set to zero; the record pointer starts at zero. On
magnetic tape an EOF is written to the tape when the le is closed even if
no data is written.
2
Write-Save access only, if the le's security provisions allow write access.
Previous data in the le is not deleted. FREAD, FREADSEEK, FUPDATE, and
FREADDIR intrinsic calls cannot reference this le. The EOF is not changed;
the record pointer starts at zero. Therefore, data is overwritten if FWRITE is
called. The system changes this value to append for message les.
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
11
cont'd
Item Description
3
Append access only, if the le's security provisions allow either
append or write access. FREAD, FREADDIR, FREADSEEK,
FUPDATE, FSPACE, FPOINT, and FWRITEDIR intrinsic calls
cannot reference this le. The record pointer is set to EOF
prior to each FWRITE. For disk les, the EOF is updated after
each FWRITE call. Therefore, data cannot be overwritten.
4
Read/Write (I/O) access only, if the le's security provisions
allow both read and write access. If both read and write access
are not allowed, the access type is limited to that specied in
the security provisions (either read or write). Any le intrinsic
can be issued except FUPDATE for this le. The EOF is not
changed; the record pointer starts at zero. This option is not
valid for message les.
5
Update access only, if the le's security provisions allow both
read and write access. If both read and write access are not
allowed, the access type is limited to that specied in the
security provisions (either read or write). All le intrinsics can
be issued, including FUPDATE, for this le. The EOF is not
changed; the record pointer starts at zero. This option is not
valid for message les.
6
Execute access only, if the le's security provisions allow
execute access. This allows read/write access to any loaded le.
The program must be running in privileged mode to specify
execute access. This option is not valid for message les.
7
Execute-Read access only, if the le's security provisions allow
execute access. This allows only read access to a loaded le.
The program must be running in PM to specify execute-read
access. This is changed to execute access for KSAM, CIR, and
RIO les. Not valid for message les.
8
Reserved for MPE/iX. No access, opens the le or directory
without any access checking. A process must be executing in
system code to use this access type.
9
Directory read access, opens a directory for directory read
access. Directories can only be opened for no access or directory
read access. Files cannot be opened for directory read access.
FIFO les should be opened for Read Access Only (0) or Write Access Only (1).
Other access types can cause unexpected results to occur.
Command Definitions
4-339
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
12
I32
Item Description
Dynamic locking:
Passes a value enabling/disabling le locking for the le. When specied, the
FLOCK and FUNLOCK intrinsics can be used to dynamically permit/restrict
concurrent access to a disk le by other processes at specied times.
The following values are valid:
0
Disallow dynamic locking/unlocking
1
Allow dynamic locking/unlocking
Default: 0
The process can continue this temporary locking/unlocking until it closes the le.
If several accessors are sharing the le, they must all specify, or not specify, this
option. For example, if a le is opened with the dynamic locking option enabled,
and a subsequent accessor tries to open the le with dynamic locking disabled,
that subsequent attempt to open fails.
Dynamic locking/unlocking is possible through the equivalent of a global resource
identication number (RIN) assigned to the le and temporarily acquired by
HPFOPEN .
Accessors that have opened a le with the dynamic locking option enabled must
access the le through the FLOCK and FUNLOCK intrinsics to gain exclusive access
to the le. Since the use of these intrinsics is discretionary, however, all accessors
must agree to use FLOCK and FUNLOCK when writing to a le to guarantee
exclusive access. File locking is advised, but is not mandated by MPE/iX.
Lock access must be at the account, group, and le levels for HPFOPEN to grant
this option. (Lock access is available if lock, execute, append, or write access is
set at these levels.) This option is ignored for les not residing on disk.
This itemnum may only be specied with the disallow dynamic locking value (0)
when used with directories.
(ASC) Not used for asynchronous devices.
4-340
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
13
I32
Item Description
Exclusive:
Passes a value indicating continuous exclusive access to the le, from open to
close. Use this option when performing a critical operation (for example,
updating the le).
The following values are valid:
0
If itemnum =11 species read only access, read-share access takes eect.
Otherwise, exclusive access takes eect. Regardless of which access option
was selected, FFILEINFO reports zero. A zero (default) value for the
itemnum species that if the access type is read, directory read, or no
access (itemnum 11 equal to 0, 8, or 9) then shared access takes eect;
otherwise exclusive access takes eect.
1
Exclusive access. After the le is opened, any additional HPFOPEN/FOPEN
requests for this le, whether issued by this process or another process, are
prohibited until this process issues the FCLOSE request or terminates. If any
process is already accessing this le when an HPFOPEN/FOPEN call is issued
with exclusive access specied, an error status is returned to the process. If
another HPFOPEN/FOPEN call is issued for this le while exclusive access is in
eect, an error code is returned to the process that issued that
HPFOPEN/FOPEN call. Request exclusive access only if the lock access mode is
allowed by the security provisions for the le. For message les, specifying
this value means that there can be only one reader and one writer.
Exclusive access cannot be used with directories.
2
Read-Share access (semi-exclusive access). After the le is opened,
concurrent write access to this le through another HPFOPEN/FOPEN request
is prohibited, whether issued by this process or another process, until this
process issues the FCLOSE request or terminates. A subsequent request for
the read/write or update itemnum =11 obtains read access. However, other
types of read access are allowed. If a process already has write access to the
le when this HPFOPEN call is issued, an error code is returned to the calling
process. If another HPFOPEN/FOPEN call that violates the read-only
restriction is issued while read-share access is in eect, that call fails and an
error code is returned to the calling process. You can request read-share
access only if you are allowed the lock access mode by the security
provisions for the le. For message les, specifying this value means that
there can be multiple readers, but only one writer.
3
Share access. After the le is opened, this permits concurrent access to this
le by any process, in any access mode, subject to other basic security
provisions in eect. For message les, specifying this value means that there
can be multiple writers and one reader.
Default: 0
(ASC) This option is ignored for devices.
FIFO les should be opened for Share Access (3). Other exclusive accesses to le
will cause unexpected results to occur.
Command Definitions
4-341
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
14
I32
Item Description
Multiaccess:
Passes a value indicating how the le's record pointer is to be shared. This
option is useful for sharing standard input devices where there is some natural
sequence of access to the le. This option permits processes located in dierent
jobs or sessions to open the same le and share that le's record pointer.
The following values are valid:
0
No multiple process access allowed. A unique record pointer is created for
this access to the le. For message les, the le system sets the multiaccess
option to 2 when a zero is specied for this option.
1
Intrajob multiprocess access allowed. A record pointer is shared with all
other opened les of the same name in the same job/session who opened the
le with itemnum =14 is set to either 1 or 2.
2
Interjob multiprocess access allowed. A record pointer is shared with all
other opened les of the same name on the system. This is the same as
specifying the GMULTI option in a FILE command.
Default: 0
Native byte stream access (see item 77) is opened regardless of the value of this
itemnum . This itemnum is also ignored for directories since it is not applicable.
(ASC) Not used for asynchronous devices.
15
I32
Multirecord:
Passes a value indicating that individual read or write requests are not conned
to record boundaries.
The following values are valid:
0
Nonmultirecord mode (NOMULTI)
1
Multirecord mode (MULTI)
Default: 0
If the number of half words or bytes to be transferred (specied in the length
parameter of the read or write request) exceeds the size of the physical record
(that is, a block) that is referenced, the remaining half words or bytes are taken
from subsequent successive records until the number specied by length has been
transferred. For message (MSG) les not accessed with itemnum =17 enabled, the
le system sets this option to zero. This option is available only if itemnum =46
is set to 1.
(ASC) This option is not used for printers.
4-342
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
16
I32
Item Description
Nowait I/O:
Allows the accessor to initiate an I/O request and to have control returned before
the completion of the I/O. This option implies the inhibit buering option; if
NOBUF is not specied, the le system does it. Multirecord access is not available.
This option is not available if the le is located on a remote computer. When
opening nonmessage les, the process must be running in PM (execution level 2)
to specify this option. Set itemnum =29 to 3 if the le is to be accessed while in
user mode (execution level 3).
The following values are valid:
0
Nowait I/O not in eect
1
Nowait I/O in eect
Default: 0
Directories may not be opened using Nowait I/O (1).
17
I32
Copy mode:
Passes a value that determines if any le should be treated as a standard
sequential le so it can be copied by logical record or physical block to another
le.
Byte stream les and directories are accessed using normal access (0) regardless
of the value specied for this itemnum .
The following values are valid:
0
The le is accessed as its own le type (for example, a message le is
treated as a message le).
1
The le is to be treated as a standard (STD) le with variable-length
records. For message les, this allows nondestructive reading of an old
message le at either the logical record or physical block record level. Only
block-level access is permitted if the le is opened with write access. This
prevents incorrectly formatted data from being written to the message le
while it is unprotected. To access a message le in copy mode, a process
must have exclusive access to the le.
(KSAM) Not allowed for KSAM XL les.
Default: 0
Command Definitions
4-343
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
18
@32
Item Description
Short-mapped:
Returns a short pointer to the beginning of the data area of the le. This option
maps the le into short pointer space. A short-mapped le can be 4 megabytes in
length. The calling process can have up to 6 megabytes of short-mapped les
open at a time. Use the pointer as a large array of any type to eciently access
the le.
A le previously opened normally (not mapped) or with the long-mapped option
is not accessible with the short-mapped option. If this option is specied with the
le already opened into long pointer space, an error results.
A loaded program le or a loaded library le is not accessible with the
short-mapped option. A le cannot be loaded that is currently opened with the
short-mapped option.
Sharing of short pointer les is provided through normal le system sharing
mechanisms, for example, use of the exclusive option. With the short-mapped
le, all le system intrinsics, applicable to the le, can be used. FREAD and
FWRITE calls can be mixed with the short-mapped access.
Standard (STD) type disk les of xed or undened record length can be
accessed short-mapped with the access type option set to any value. Standard
type disk les of variable record length can be accessed short-mapped only if the
access type option is set to read-only access. KSAM les can be accessed
short-mapped only if the access type option is set to read-only access and the
copy mode option is set to 1.
Directories may not be opened using short-mapped access.
Default: No short pointer returned
(ASC) Not used for asynchronous devices.
19
I32
Record size:
Passes the size, in bytes, of the logical records in the le. Valid range is
dependent upon both storage format (ASCII or binary) and record format. For
xed-length and undened-length ASCII les, a record size can be specied in
the range 1..32,767. For variable-length ASCII les, and for xed-length,
variable-length, and undened-length binary les, a record size can be specied
in the range 1..32,766.
HPFOPEN rounds up odd values to the next highest even number (equivalent to
the nearest half word boundary) if the le is ASCII with variable-length record
format, binary with xed-length, variable-length, or undened-length record
format.
For example, if a record size of 105 is specied for a xed-length binary le,
HPFOPEN sets the record size to 106; if a record size of 233 is specied for a
xed-length ASCII le, the record size remains the same as it was when specied.
The value specied for this itemnum is ignored when a byte stream le or
hierarchical directory is created. Byte stream les are created with a logical
record size of one byte (1). Hierarchical directories are created with a logical
record size of 32 bytes (32).
Default: 256
4-344
(ASC) For terminal and printer les, no rounding up occurs if a record size
consisting of an odd number of bytes is specied. The record size can be dierent
from the port conguration. The default is the congured record size (normally
40 words for terminals, 66 words for printers).
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
20
CA
Item Description
Device name:
Passes the logical device number, in ASCII form, of a specic device. The le is
assumed to be permanent. If the device name option is specied, the
nonshareable device should be ready prior to the HPFOPEN call (otherwise, an
error results).
Only one of the following options can be in eect when a le is opened:
itemnum =20
itemnum =22
itemnum =23
itemnum =42
Default: Disk le located on the volume class DISC associated with the group in
which le resides.
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%devname% (% is the delimiter, devname is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
21
@64
Long-mapped:
Returns a long-pointer to the beginning of data of the le. This option maps the
le into long pointer space. A long-mapped le can be up to 2-gigabytes in size.
There is no limit to the number of long-mapped les a process can have open at
one time. The pointer can be used as a large array of any type to access the le.
A loaded program le or a loaded library le is not accessible, and a le cannot
be loaded with this option.
Sharing long-pointer les is provided through normal le system le sharing
mechanisms. All le system intrinsics applicable to the le can be used. FREAD
and FWRITE calls can be mixed with this option.
Standard (STD) disk les of xed or undened record length can be accessed
with this option. Standard disk les of variable record length can be accessed
only if itemnum =11 (read-only access). Standard disk les of variable record
length and KSAM les can be accessed only if itemnum =11 (read-only access)
and itemnum =17 (set to 1).
Directories may not be opened using long-mapped access.
Default: Not returned
(ASC) Not used for asynchronous devices.
Command Definitions
4-345
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
22
CA
Item Description
Volume class:
Passes a character array representing a volume class name where the le space is
to be restricted. This option is applicable only at le creation.
A volume class is a subset of volumes within a volume set. The volume class
name must be a valid volume class name residing on the volume set bound to the
volume (the volume set is an attribute of the group in which the le resides).
Only one of the following options can be in eect when a le is opened with this
option:
itemnum =20
itemnum =22
itemnum =23
itemnum =42
Default: A disk le located on the volume class DISC associated with the group
in which le resides.
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%volclass% (% is the delimiter, volclass is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
This itemnum may not be specied when creating hierarchical directories.
(ASC) Not used for asynchronous devices.
23
CA
Volume name:
Passes a character array representing a volume name that restricts the le
specied to a specic volume. The volume must reside within the volume set of
the group where the le resides. This option is applicable only at le creation.
Only one of the following options can be in eect when a le is opened with this
option:
itemnum =20
itemnum =22
itemnum =23
itemnum =42
Default: A disk le located on the volume class DISC associated with the group
in which the le resides.
This itemnum may not be specied when creating hierarchical directories.
(ASC) Not used for asynchronous devices.
24
I32
Density:
Passes the tape density required when writing to a tape le. This option is
applicable only when writing to a tape on a drive that supports more than one
density. When reading from a tape, the density of the tape overrides this option
Default: The highest density available on the device opened.
(ASC) Not used for asynchronous devices.
4-346
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
25
CA
Item Description
Printer environment:
Passes the name of a le that contains a printer environment. This option is valid
only for specied printer devices.
If opening an Hewlett-Packard 268x page printer le, specify an optional printing
environment for the job. The printing environment is dened as all of the
characteristics of the printed page that are not part of the data itself, including
the page size, the margin width, the character set, the orientation (horizontal or
vertical), and the name of forms to use. If an environment le is not specied,
the le system selects a default printer environment.
Any environment selected remains active until replaced by a new environment, or
until a call to FCLOSE (close the printer).
Default: No printer environment le specied
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example,
%envname% (% is the delimiter, envname is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
26
CA
Remote environment:
Passes the node name of the remote computer where the le is located. This
option is used when referencing a le located on a remote computer.
Default: No node name passed (local le access)
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example,
%envname% (% is the delimiter, envname is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
A remote environment cannot be specied when creating or opening les in the
HFS name space or in byte stream les.
27
I32
Output priority:
Passes the output priority to be attached to the le for spooled output. This
option is applicable only to spooled devices. The output priority must be a
number between 1 (lowest priority) and 13 (highest priority), inclusive. If the
value specied is less than the current outfence set by the system operator, le
printing is deferred until the operator raises the output priority of the le or
lowers the outfence. This option can be specied for a le already opened (for
example, $STDLIST), where the highest value supplied before the last FCLOSE
takes eect. This option is ignored for nonspooled devices.
Default: 8
Command Definitions
4-347
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
28
CA
Item Description
Spooled message:
Passes a spooler message associated with a spoolle. For example, a message is
passed that can be used for telling the system operator what type of paper to use
in the line printer. This message must be displayed to the system operator and
veried before the le can be printed on a line printer. The number of characters
allowed <=48; any quantity > 48 characters is truncated.
Default: No spooled message specied
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%message% (% is the delimiter, message is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
29
I32
Privileged access:
Passes a value that temporarily restricts access to the le number returned from
HPFOPEN to a calling process whose execution level is equal to or less than the
value specied in this option. This restriction lasts until the le associated with
the restricted le number is closed. Do not specify a value less than the execution
level of the calling process.
The following values are valid:
0
Privilege level zero (most privileged level)
1
Privilege level one
2
Privilege level two
3
Privilege level three (least privileged level)
Default: The execution level of the calling process
30
I32
Labeled tape type:
Passes a value that indicates tape label type information. This option is valid
only for labeled tapes. The following values are valid:
0
ANSI standard labels
1
IBM standard labels
Default: 0
(ASC) Not used for asynchronous devices.
4-348
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
31
CA
Item Description
Labeled tape expiration:
Passes the date of the expiration of the le or the date after which the
information in the le is no longer useful, in the format MM/DD/YY . The le can be
overwritten after this date. If the default is specied, the le can be overwritten
immediately. In a volume set, le expiration dates must always be equal to or
earlier than the date on the previous le.
Default: No expiration date specied
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example,
%expdate% (% is the delimiter, expdate is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
(ASC) Not used for asynchronous devices.
32
CA
Labeled tape sequence:
Passes one of the following character arrays indicating the position of the le in
relation to other les on the tape:
0
Causes a search of all volumes until the le is found.
1.. Species the position of the le relative to the current le on the tape.
9999
ADDF Causes the tape to be positioned so as to add a new le at the end of the
volume or last volume in a multivolume set.
NEXT Positions the tape at the next le on the tape. If this is not the rst
HPFOPEN/FOPEN for the le and a rewind occurred on the last close, then the
position remains at the beginning of the previous le.
Default: No array passed (no sequence indicated)
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example,
%position% (% is the delimiter, position is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
(ASC) Not used for asynchronous devices.
33
I32
User labels:
Passes the number, in the range 0..254, of user-label records to be created for the
le. Applicable for new disk les only.
Default: 0
This itemnum may not be specied when creating hierarchical directories.
(ASC) Not used for asynchronous devices.
Command Definitions
4-349
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
34
I32
Item Description
Spooler copies:
Passes a value in the range 1..127 indicating the number of copies of the entire
le to be produced by the spooling facility. This option is applicable to spooled
devices only. This option can be specied for a le already opened (for example,
$STDLIST ), where the highest value supplied before the last FCLOSE takes eect.
The copies do not appear continuously if the system operator intervenes or if a
le of higher output priority becomes READY before the last copy is complete.
This option is ignored for nonspooled output devices.
Default: 1
35
I32
File size:
Passes the maximum le capacity:
For variable-length records, the capacity is expressed in blocks
(blockitem#=recordsize * blockfactor ).
For xed-length and undened-length records, the capacity is expressed in
logical records.
The maximum le size for standard and KSAM XL les is 4,294,901,759 bytes
(4 gigabytes less 64K bytes).
The maximum le size for a CM KSAM data le is 2 gigabytes and for a CM
KSAM key le, 2 gigabytes.
The maximum le size of 500 megabytes, for RIO and circular is dependent
upon both the record size and the number of extents dened for the le:
For circular and RIO les, recsize =256 bytes and numextent =32.
This option is applicable only at le creation.
Default: 2 gigabytes
This itemnum may not be specied when creating hierarchical directories.
(ASC) Not used for asynchronous devices.
36
I32
Initial allocation:
Passes a positive integer value indicating the number of records to be allocated to
the le initially. This option is applicable only at le creation.
Default: 0
This itemnum may not be specied when creating hierarchical directories.
(ASC) Not used for asynchronous devices.
4-350
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
37
I32
Item Description
File code:
Passes a value that can be used as a le code to identify the type of le. This
code is recorded in the le label and is accessible through the FFILEINFO
intrinsic. This option is applicable only at le creation (except when opening an
old le that has a negative le code).
If the program is running in user mode, specify a le code in the range 0..32,767
to indicate the le type being created. Programs running in user mode can access
les with positive le codes only.
If the program is running in privileged mode, specify a le code in the range
-32,768..32,767. Programs running in privileged mode can access les with a le
code in the range -32,768..32,767. If an old le is opened that has a negative le
code in its le label, the le code specied must match the le code in the le
label (otherwise, an error results).
File codes cannot be specied for hierarchical directories. Negative le codes may
be used only for les in MPE groups. A status.info of -315 is returned when
negative le codes are specied for les outside MPE groups.
Default: 0
(ASC) Not used for asynchronous devices.
38
I32
File privilege:
Passes a value that determines a permanent privilege level to be associated with
a newly created le. This option permanently restricts le access to a process
whose execution level is less than or equal to the specied value. A value cannot
be specied for less than the execution level of the calling process. This option is
applicable only at le creation.
The following values are valid:
0
Privilege level zero (most privileged level)
1
Privilege level one
2
Privilege level two
3
Privilege level three (least privileged level)
Default: 3
Command Definitions
4-351
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
39
I32
Item Description
Access type:
Passes a value indicating how to use the le, either sequentially or randomly. The
le system uses this information to determine the most ecient prefetching
algorithm to improve the performance of the le access.
The following values are valid:
0
Access the le sequentially
1
Access the le randomly
Default: 0
(ASC) Not used for asynchronous devices.
40
I32
Block factor:
Passes the number of logical records to be contained in one physical record
(block). This value is used to calculate the physical record size (block size) for
disk and magnetic tape les. Valid ranges are 1..32,767. This option is applicable
only at le creation.
For xed-length records, this option species the actual number of records in a
block. For variable-length records, this option is interpreted as a multiplier used
to compute the block size (record size option * block factor option ). For
undened-length records, this option is always one logical record per block.
This itemnum may not be specied when creating hierarchical directories.
Default: 1 for les opened NOBUF; for les opened BUF, it is calculated by dividing
the specied records into the block size congured for the device.
(ASC) Not used for asynchronous devices.
41
I32
Name syntax:
Species which of three name semantics will be used to interpret the lename
passed to HPFOPEN:
0
MPE-escaped semantics
1
MPE-only sematics
2
POSIX semantics
MPE-escaped name semantics is the default value for this itemnum . The selected
name semantics do not apply to le equations specied through itemnum 52 or
system-dened le references specied through itemnum 5.
4-352
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
42
CA
Item Description
Device class:
Passes a device class where the le resides. The le system uses the device class
name to select a nonshareable device from a congured list of available devices.
The name can have a length of up to eight alphanumeric characters, beginning
with a letter (for example, TAPE). If a device class is specied, the le is allocated
to any available device in that class.
Only one of the following options can be in eect when a le is opened:
itemnum =20
itemnum =22
itemnum =23
itemnum =42
Default: A disk le located on the volume class DISC associated with the group
in which le resides.
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%devclass% (% is the delimiter, devclass is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
This itemnum may not be specied when creating hierarchical directories.
Hierarchical directories created on the system volume set is allocated on any
volume within the set. Hierarchical directories created on non-system volume sets
is allocated on the master volume.
43
record
UFID:
Passes a unique le identier (UFID) to provide a fast opening of an old disk le.
A UFID is a record structure, 20 bytes in length, that uniquely identies a disk
le. Using this option avoids a directory search. Obtain the UFID of an opened
le by calling FFILEINFO. The UFID can then be passed to HPFOPEN. The le
represented by the UFID must be accessible to the process calling HPFOPEN. (All
le system security checks are made.) New les cannot be opened with this
option. If the le to be opened by the UFID contains a lockword, use
itemnum =2 to specify the le name with the lockword.
Only les in the MPE name space may be opened by UFID. An attempt to open
a le outside the MPE name space by UFID results in a status.info of -321 being
returned. Only system code may open a le by UFID in the POSIX name space.
Default: No UFID passed (a directory search is performed)
(ASC) Not used for asynchronous devices.
Command Definitions
4-353
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
44
I32
Item Description
Numbuers:
Passes the number of buers to allocate to the le. Ignored for standard disk
les. This option is useful only for slow devices (such as tapes) used in a buered
mode. Not applicable for les representing interactive terminals; a
system-managed buering method is always used.
The valid range for this option is dependent upon the le type:
For standard and KSAM les, the valid range is 1..31.
For circular and RIO les, the valid range is 1..16.
For message les, the valid range is 2..16. (If a 1 is specied, the le system
sets this option to 2 and no error is returned.)
This option must not specify a number of buers whose combined size exceeds
the physical capacity of the le.
This itemnum is ignored when creating hierarchical directories.
Default: 2
(ASC) Not used for asynchronous devices.
45
CA
Fill character:
Passes two ASCII characters that determine what padding character to use at
the end of blocks or unused pages, and the padding used by itemnum =53. Do
not use delimiter characters for this option. The ll character must be a 2 byte
array. The rst character only is used as the padding character. The second
character is reserved for future use. This option is applicable only at le creation.
Default: Null characters for a binary le and ASCII blanks for an ASCII le.
The default ll character for byte stream les is the null character. The ll
character is null for hierarchical directories regardless of the value specied for
this itemnum .
4-354
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
46
I32
Item Description
Inhibit buering:
Passes a value enabling/disabling automatic operataing systembuering. If NOBUF
is specied, I/O is allowed to take place directly between the data area and the
applicable hardware device.
The following values are valid:
0
Allow normal buering (BUF)
1
Inhibit buering (NOBUF)
Default: 0
NOBUF access is oriented to physical block transfer rather than logical record
transfer. If NOBUF and a variable-length record structure are specied in
itemnum =6 and the le does not have a variable-length record format, then the
format is changed internally to an undened-length record format. When
performing an FWRITE, set up the variable structure.
With NOBUF access, responsibility for blocking and deblocking of records in the
le belongs to the program. To be consistent with les built using buered I/O,
records should begin on half word boundaries. When the information content of
the record is less than the dened record length, you must pad the record with
blanks if the le is ASCII, or with zeros if the le is binary.
The record size and block size for les manipulated with NOBUF specied follow
the same rules as those les that are created using buering. The default
blocking factor for a le created under NOBUF is one.
If a le is opened NOBUF without multirecord mode specied in itemnum =15,
then transfer a maximum of only one block of data per read or write.
The end-of-le (EOF) marker, next record pointer, and record transfer count are
maintained in terms of logical records for all les. The number of logical records
aected by each transfer is determined by the size of the transfer.
Transfers always begin on a block boundary. Those transfers that do not transfer
whole blocks leave the next record pointer set to the rst record in the next
block. The EOF marker always points at the last record in the le.
For les you have opened NOBUF, the FREADDIR , FWRITEDIR, and FPOINT intrinsics
treat the recnum parameter as a block number.
Indicate non-RIO access to an RIO le by specifying the le NOBUF. Use the
physical block size from FFILEINFO to determine the maximum transfer length.
For message les, the le system normally resets itemnum =46 to zero. However,
a message le can be opened with NOBUF if itemnum =17 is set to 1; this
determines access to the le record-by-record or by block.
If writing to a message le, open it NOBUF if itemnum =17 to access the le
block-by-block.
Native byte stream access opens NOBUF (1) regardless of the value specied for
this itemnum . This itemnum is ignored for directories since a physical block
transfer interface is not provided for directories.
(ASC) Not used for asynchronous devices.
Command Definitions
4-355
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
47
I32
Item Description
Numextents:
Passes a value in the range 1..32 that determines the number of extents for the
le. If a value of 1 is specied, the le is created as one contiguous extent of disk
space. If a value greater than 1 is specied, a variable number of extents (with
varying extent sizes) is allocated on a need basis. This option is applicable only
at le creation.
(ASC) Not used for asynchronous devices.
Default: 1
This itemnum may not be specied when creating hierarchical directories.
48
I32
Reverse VT:
Passes a value indicating whether or not the given device name is to be allocated
on a remote machine. Specify the remote environment in the same open request,
using either the formal designator option or the remote environment option.
Reverse VT behaves nearly the same as a terminal opened through remote le
access, except that no session is required on the remote machine.
The following values are valid:
0
No reverse VT
1
Reverse VT
Default: 0
49
4-356
Reserved for the operating system
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
50
I32
Item Description
Final disposition:
Passes a value indicating the nal disposition of the le at close time (signicant
only for les on disk and magnetic tape). A corresponding parameter in a FILE
command can override this option, unless le equations are disallowed with
itemnum =9.
The following values are valid:
0
No change. The disposition remains as it was before the le was opened. If
the le is new, it is deleted by FCLOSE; otherwise, the le is assigned to the
domain it belonged to previously. An unlabeled tape le is rewound. If the
le resides on a labeled tape, the tape is rewound and unloaded.
1
Permanent le. If the le is a disk le, it is saved in the system le domain.
A new or temporary le on disk has an entry created for it in the system
(permanent) le directory. If a le of the same name already exists in the
directory, an error code is returned at close time and the le remains open.
If the le is a permanent le on disk, this domain disposition has no eect.
If the le is stored on magnetic tape, the tape is rewound and unloaded.
2
Temporary job le (rewound). The le is retained in your temporary
(job/session) le domain and can be requested by any process within your
job/session. If the le is a disk le, the uniqueness of the le name is
checked. If a le of the same name already exists in the temporary le
domain, an error code is returned at close time and the le remains open.
When a le resides on unlabeled magnetic tape, the tape is rewound.
However, if the le resides on labeled magnetic tape, the tape is backspaced
to the beginning of the presently opened le.
3
Temporary job le (not rewound). This value has the same eect as
specifying nal disposition option itemnum =2, except that tape les are not
rewound. In the case of unlabeled magnetic tape, if the FCLOSE is the last
done on the device (with no other FOPEN/HPFOPEN calls outstanding), the
tape is rewound and unloaded. If the le resides on a labeled magnetic tape,
the tape is positioned to the beginning of the next le on the tape.
4
Released le. The le is deleted from the system.
5
Convert a permanent le to a temporary le. The le is removed from the
permanent le directory and placed in the temporary le directory.
(Privileged mode capability is required to use this option.)
Default: 0
For more information on le disposition at close time, refer to the description of
the FCLOSE intrinsic.
(ASC) Not used for asynchronous devices.
Command Definitions
4-357
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
51
String
Item Description
Pascal XL string:
Passes a formal le designator that follows MPE/iX le naming conventions,
using the Pascal XL STRING type format. This option is identical to
itemnum =2 except for the type of item. No delimiters are needed.
Default: No string passed
When you use HPFOPEN to open a le, you may use either itemnum =2 or you may
use itemnum =51; you may not use both.
As the default, the formal le designator is interpreted according to
MPE-escaped semantics. To choose another syntax, use itemnum 41.
The le referred to by formaldesig can be either an MPE le (i.e., one that uses
MPE syntax) or it can follow HFS syntax. If formaldesig follows MPE syntax,
the le name can include password, group, and account specications. The le
name can backreference a le equation and optionally be preceded by an asterisk.
If formaldesig follows HFS syntax, the le name must start with either a dot (.)
or a slash (/).
The le referred to by formaldesig may reside either in an MPE group or in an
HFS directory. For les located in HFS directories, traverse directory entries
(TD) access is required to all directories specied in formaldesig . If there is no
TD access, HPFOPEN fails and a value of -180 is returned in the status.info
parameter. If you are using HPFOPEN to create a le or hierarchical directory and
you lack of create directory entry (CD) access, status .info will return a value of
-179.
52
CA
File equation string:
Passes a character string that matches the le equation specication syntax
exactly. (Refer to the FILE command in the MPE/iX Commands Reference
Manual Volumes 1 and 2 (32650-90003 and 32650-90364).) This option allows
the specication of options available in the FILE command.
The formaldesig parameter and lereference parameter can contain embedded
command interpreter variables and expressions. However, there cannot be more
than 8-characters in each of these components (lename, lockword, groupname,
accountname ) including the command interpreter variable and expression
characters.
Default: No string passed
A character placed in the rst element designates the delimiter used by HPFOPEN
to search for the end of the character array. The delimiter can appear again only
following the last valid character of the character array, for example:
%leequation% (% is the delimiter, leequation is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)
The formaldesignator in the le equation string must belong to the MPE name
space. The lerefence in the le equation string is interpreted using MPE-escaped
semantics. Both the formaldesignator and the lereference in the le equation
string may also contain embedded command interpreter variables or expressions.
4-358
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
53
I32
Item Description
ASCII/binary:
Passes a value indicating whether ASCII or binary code is to be used for a new
le when it is written to a device that supports both codes. For disk les, this
aects padding that can occur when issuing a direct-write intrinsic call
(FWRITEDIR) to a record that lies beyond the current logical end-of-le indicator.
By default, magnetic tape and les are treated as ASCII les. This option is
applicable only at le creation.
The following values are valid:
0
Binary le
1
ASCII le
Default: 0
(ASC) Not used for asynchronous devices.
54
REC
KSAM parm:
Passes a record that denes the keys for a new KSAM le.
(KSAM XL) For KSAM XL les, refer to the parm parameter discussion in the
Using KSAM XL (32650-90168).
(KSAM/3000) The record must be at least 34 bytes in size. For details, refer to
the ksamparam parameter discussion in the KSAM/3000 Reference Manual
(30000-90079).
Default: No record passed
(ASC) Not used for asynchronous devices.
55
56
Reserved for the operating system
I32
Object class:
Passes a user object class number, in the range 0..10, that is associated with the
le.
Default: Determined by the le code for system and subsystem les, and by the
le type and record type for normal user les.
57
Reserved for the operating system
Command Definitions
4-359
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
58
Reserved for the operating system
59
Reserved for the operating system
60
Reserved for the operating system
61
Reserved for the operating system
64
BA
Access Control Denition:
Passes a byte array dening the access control denition (ACD) to be attached to
a new le. The byte array has a length of 1 to 279 bytes. Unlike other HPFOPEN
options that expect a delimiter at both the beginning and the end of the byte
array, this option only expects a trailing carriage return character as a delimiter,
for example,
(X:@.@;R,W:MGR.SYS;RACD:JOHN.SMITH)<cr>
Where, the <cr> is the carriage return character (13, 0x0D).
The ACD assigned to a newly created le or directory may be dierent from the
ACD specied as the value of this itemnum . If a process' le mode creation mask
(cmask) is initialized, it modies the ACD.
74
Header/Trailer:
Enable/disable standard headers/trailers:
0 Enable header and trailer (default)
1 Disable header
2 Disable trailer
3 Disable header and trailer
Provides a standard way for the spooler to control the printing banners.
Valid only for the initial HPFOPEN call to the printer and prevents the header from
being printed. On the last FCLOSE, the trailer is not printed.
4-360
Command Definitions
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
77
I32
Item Description
Data format
Allows the caller to select a dierent format to view the data in the le. The
current valid values for this item are:
0
Use the standard record based view of accessing the le. This is
the default value for all opens. For conventional les, the le is
record based. For directories, the standard non-privileged
directory information is returned when the HPDIRREAD intrinsic
is called. When this value is specied with a byte stream le,
access to the le is emulated to appear like a buered variable
record le. This is the default.
1
When this value is specied, calls to HPDIRREAD returns
privileged directory information including the UFID and link ID
of the entry. Note that this value is only applicable to directory
les. This value is ignored for all other le types. In order to
specify this value, the caller must be executing in system code.
2
When this value is specied, the system attempts to let the
caller access the le as a native byte stream le. Byte stream
emulation is supported for ordinary xed and variable length
record les as well as for les with the byte stream record type.
If this value is requested against a le type that does not
support byte stream access, an error is returned.
Specifying any value other than the values described above will result in an error.
79
I32
POSIX Non-Block Mode
Specifying this itemnum allows the caller to open a le with the POSIX
Non-Block mode. This item is useful for a subset of les (including pipes and
FIFO's) and is ignored for all other les. The behavior of the HPFOPEN call
with this option is dependent on the type of le being opened.
The current valid values for this item are:
0
This value indicates that Non-Block mode is o. This is the
default value.
1
This value indicates that Non-Block mode is on.
Specifying any value other than those described above will result in error.
Command Definitions
4-361
HPFOPEN
Table 4-20. HPFOPEN Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
80
I32
Reserved for the operating system.
81
I32
Symbolic link option:
This itemnum allows the caller to specify dierent options when traversing
through or opening a symbolic link. The valid values for this itemnum are
described below:
0
Follow symbolic links. This is the default value for this option.
When a symbolic link is encountered it is traversed according
to the path specied in the symbolic link.
1
Does not follow symbolic links. If the nal component of a path
is a symbolic link, then no traversal is done and the symbolic
link is opened. Symbolic links that occur prior to the last
component is traversed.
Specifying any value other than those above will result in error.
4-362
Command Definitions
HPFOPEN
Operation Notes
Enables creation of a new le on a shareable device and denes the physical characteristics of
that le prior to access. Enables access to existing les. Returns a le number to the calling
process that uniquely identies the le. Use the le number to reference the le in calls to
other intrinsics.
Related Information
Intrinsics
Commands
Manuals
FOPEN
None
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL
(32650-90168), and KSAM/3000 Reference Manual (30000-90079)
Command Definitions
4-363
HPFPCONVERT
NM and CM callable.
Converts data between binary oating-point formats.
Syntax
*
*
I16V
I16V
HPFPCONVERT( source,destination,sformat,dformat,
I32
I16
I16V
status,exceptions,roundmode)
Parameters
source
any supported real type by reference (required)
destination
Passes the oating-point number to be converted. Constants are not
acceptable. You can specify a reference parameter of any supported real type
in the intrinsic call statement. The format is identied by sformat .
any supported real type by reference (required)
sformat
Returns the converted oating-point number. If status.info is less than zero,
the number is not converted. Any supported real type can be returned to the
intrinsic call statement. The format is identied by dformat .
16-bit signed integer by value (required)
The oating-point format of the binary number supplied by source . This is
the format of the original number. Valid formats are:
Value
1
2
3
4
5
4-364
Command Definitions
Meaning
Hewlett-Packard 3000 32-bit
Hewlett-Packard 3000 64-bit
IEEE 32-bit
IEEE 64-bit
IEEE 128-bit
HPFPCONVERT
dformat
16-bit signed integer by value (required)
The destination oating-point format. This is the looking forward to some
leisure and alternative nursing choices.format of the converted number. Valid
formats are:
Value
1
2
3
4
5
status
Meaning
Hewlett-Packard 3000 32-bit
Hewlett-Packard 3000 64-bit
IEEE 32-bit
IEEE 64-bit
IEEE 128-bit
32-bit signed integer by reference (optional)
Returns the status of the HPFPCONVERT intrinsic call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
refer to the MPE/iX Error Message Manual Volumes 1, 2 and 3 (32650-90066,
32650-90152, and 32650-90368) for a description of its value. A positive value
indicates that the conversion was made, but an exception occurred and an
exceptions parameter was not supplied. The exception conditions are listed in
the exceptions parameter description.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPFPCONVERT is 193.
Command Definitions
4-365
HPFPCONVERT
exceptions
16-bit signed integer by reference (optional)
Returns any exception conditions that occurred during the conversion. If
status.info is less than zero, then exceptions is not modied because no
conversion is done. If this parameter is not present, the value is returned in
status.info .
Only the following values can be returned:
Value
0
1
3
5
8
roundmode
Meaning
No exceptions
Inexact only (native mode destination only)
Underow and inexact
Overow and inexact
Invalid operation
If underow or overow occurs during conversion then inexact is also signaled.
16-bit unsigned integer by value (optional)
The rounding mode (not applicable if destination is an Hewlett-Packard 3000
format).
Value
0
1
2
3
Meaning
Round to nearest, to even if tie (default)
Round to zero
Round to positive innity
Round to negative innity
Operation Notes
The HPFPCONVERT intrinsic accepts a source binary oating-point number and converts it to
the equivalent destination binary oating-point format. You must specify the format of the
source and destination numbers. Optionally, you can specify the rounding mode.
The conversion is performed by regarding the source number as innitely precise and with
unbounded range, and then rounding it to t the designated destination format. Rounding
is performed according to the formal rules for the rounding mode specied. Rounding
methods and exception signaling are determined solely from the destination format and are
independent of the source format.
Conversion is performed as if all arithmetic traps are disabled. No trapping to user-supplied
or system-supplied arithmetic trap routines is done.
4-366
Command Definitions
HPFPCONVERT
Related Information
Intrinsics
Commands
Manuals
None
None
Data Types Conversion Programmer's Guide (32650-90015).
Command Definitions
4-367
HPGETPROCPLABEL
NM callable only.
Dynamically loads a native mode (NM) executable library procedure.
Syntax
CA
U32 I32
CA
HPGETPROCPLABEL(procname,plabel,status,rstle,
B
casesensitive);
Parameters
procname
character array (required)
plabel
Passes the name of the procedure being searched for. The rst character of
procname designates the terminating character that HPGETPROCPLABEL uses
to search for the end of the name. That delimiter can appear again only
following the last valid character of the procedure name.
32-bit unsigned integer by reference (required)
status
Returns a procedure label (NM plabel) for the procedure that was found.
32-bit signed integer by reference (optional)
Returns the status of the HPGETPROCPLABEL intrinsic call. If no errors or
warnings are encountered, status returns 32 bits of zero. If errors or warnings
are encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
a positive value indicates a warning condition. Refer to the MPE/iX Error
Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPGETPROCPLABEL is 104.
4-368
Command Definitions
HPGETPROCPLABEL
rstle
character array (optional)
Passes the name of the program le or XL at which to begin searching.
The rstle parameter can be either in MPE syntax or HFS syntax. If the
name of the program le or XL is in HFS syntax, you must use an absolute
pathname. The rst character that HPGETPROCPLABEL uses to search for the
end of the le name. That delimiter can appear again only following the last
valid character of the name.
If rstle is located in the binding sequence of the calling process, then,
beginning with rstle , HPGETPROCPLABEL directs the NM loader to search
through each le in the binding sequence for the rst instance of a procedure
named procname.
If either procname is not located in the XL or procname contains
unresolved external references that must be satised in subsequent XLs, then
each XL in the binding sequence after rstle is searched.
If rstle is not located in the binding sequence, then rstle has a binding
sequence independent of the program and is bound directly to the system
libraries. Any unresolved external references found within rstle must be
resolved in the system libraries.
casesensitive
Default: System libraries
Boolean (optional)
Indicates in the following manner whether the procname parameter is case
sensitive:
FALSE
HPGETPROCPLABEL rst tries nding procname as it was
specied. If procname cannot be found, HPGETPROCPLABEL
tries to nd the procedure with the case of procname the
opposite case of the rst character of procname for example,
if you specify procname as scanforkey and the procedure
scanforkey is not found, the intrinsic searches for the
procedure SCANFORKEY.
TRUE
Default: FALSE
The procname parameter is case-sensitive.
HPGETPROCPLABEL does not alter the name in any way.
Operation Notes
The HPGETPROCPLABEL intrinsic locates a procedure found in an NM executable library le
(XL) and returns its procedure label (NM plabel). In addition, if the procedure is not yet
loaded for the process, HPGETPROCPLABEL dynamically loads the procedure.
You can then use the NM plabel to call the specied procedure dynamically, provided the
programming language contains features for making dynamic procedure calls.
Note
If you are going to use HPGETPROCPLABEL to call system intrinsics, you must
rst refer to the SYSINTR le to determine the correct parameter descriptions
(for the parameters to be passed with the returned PLABEL).
Command Definitions
4-369
HPGETPROCPLABEL
A plabel returned by HPGETPROCPLABEL is valid only for the duration of the calling process.
Related Information
Intrinsics
Commands
Manuals
4-370
None
None
Resource Management Programmer's Guide (32650-90024).
Command Definitions
HPLOADCMPROCEDURE
HPLOADCMPROCEDURE
NM callable only.
Obtains CM procedure plabel in preparation for Switch to CM through plabel.
Syntax
U16
CA
U16V
I32
plabel:=HPLOADCMPROCEDURE(procname,library,status);
Functional Return
plabel
16-bit unsigned integer (assigned functional return)
Plabel of the target CM procedure.
Parameters
procname
character array (required)
library
Passes an ASCII procedure name, left-justied and blank-padded. The name
can have a maximum of 16 characters.
16-bit unsigned integer by value (required)
Passes indicator of the CM segmented library to be searched. The valid values
are:
Value
0
1
2
3
4
Meaning
Search the system SL only. (Default)
Search the logon account SL, then the system SL.
Search the logon group SL, then logon account SL, and then
system SL last.
Search the program le's account SL, then the system SL.
Search the program le's group SL, then the program le's
account SL, and then the system SL last.
Command Definitions
4-371
HPLOADCMPROCEDURE
status
32-bit signed integer by reference (optional)
Returns the status of the HPLOADCMPROCEDURE intrinsic call. If no errors or
warnings are encountered, status returns 32 bits of zero. If errors or warnings
are encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPLOADCMPROCEDURE is 105.
Operation Notes
The HPLOADCMPROCEDURE intrinsic helps you avoid switching by name overhead. Switching by
name incurs the overhead of forming a hash probe out of the target procedure's name and
nding the name in a hash table in order to obtain the procedure's plabel. You can eliminate
this overhead by obtaining the target procedure's plabel through the HPLOADCMPROCEDURE
intrinsic. You can then supply the result returned by HPLOADCMPROCEDURE as the value of the
procname parameter in the call to the HPSWITCHTOCM intrinsic.
Related Information
Intrinsics
Commands
Manuals
4-372
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPLOADNMPROC
HPLOADNMPROC
CM callable only.
Returns the plabel of an NM procedure.
Syntax
U32
CA
I16V
CA
plabel:=HPLOADNMPROC(procname,proclen,libname,
I16V
liblen)
Functional Return
plabel
32-bit unsigned integer (assigned functional return)
Plabel of the target NM procedure.
Parameters
procname
character array by reference (required)
proclen
Passes the target procedure name. The target procedure must be contained
in an executable library (XL). If the value of procname is invalid, blank, or
does not contain the NM procedure, NL.PUB.SYS is searched.
16-bit signed integer by value (required)
libname
Passes the byte length of the procedure name.
character array by reference (required)
liblen
Passes the name of the NM library to be searched for the target. If the
value of libname is invalid, blank, or does not contain the NM procedure,
NL.PUB.SYS is searched.
16-bit signed integer by value (required)
Passes the byte length of the library name.
Operational Notes
Do not use HPLOADNMPROC to invoke a native mode (NM) system-supplied intrinsic. The result
of the call may be unpredictable.
Used to obtain the NM plabel of the target procedure. Then the plabel is used by the
HPSWTONMPLABEL intrinsic for its proc parameter.
The strings you supply as values of the procname and libname parameters must exactly
match the names of the target NM routine and its NM library, respectively.
Command Definitions
4-373
HPLOADNMPROC
Related Information
Intrinsics
Commands
Manuals
4-374
HPSWITCHTOCMPROCEDURE
None
Switch Programming Guide (32650-90014)
Command Definitions
HPMERGEEND
HPMERGEEND
NM callable only.
Releases the MERGE/XL work area and ends the merging operation.
Syntax
I32
I32A
HPMERGEEND( status,statistics);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPMERGEEND call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
statistics
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGEEND is 196.
32-bit signed integer array (optional)
Returns information on the Hewlett-Packard MERGE operation, as follows:
Value
1
2
3
4
5
Note
Meaning
Number of input les
Number of merged records
Number of bytes used for the MERGE/XL work area
CPU time in milliseconds
Elapsed time in milliseconds
The statistics array should be the same array that was passed to the
HPMERGEINIT intrinsic. It must be referenced by the same name.
Related Information
Intrinsics
Commands
Manuals
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-375
HPMERGEERRORMESS
NM callable only.
Accepts Hewlett-Packard MERGE intrinsic error code values and returns the error messages
associated with them.
Syntax
I32
CA
I32
HPMERGEERRORMESS(status,message,length);
Parameters
status
32-bit signed integer by reference
Passes the status of a previous Hewlett-Packard MERGE intrinsic call that
failed. The status value passed in is used to locate the appropriate message
catalog entry associated with the status value.
If no errors or warnings were encountered, status returns 32-bits of zero. If
errors or warnings were encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGEERRORMESS is 196.
Note
HPMERGEERRORMESS returns information on the success of its execution in the
message
character array (optional)
length
Returns the text of the error message. This parameter may be up to 80
characters long.
32-bit signed integer by reference (optional)
status parameter. It is good programming practice to specify this parameter
and check its value after the intrinsic call. If an error or warning condition is
encountered, and you did not specify the status parameter, HPMERGEERRORMESS
causes the calling process to abort.
Returns the length of the message parameter.
4-376
Command Definitions
HPMERGEERRORMESS
Related Information
Intrinsics
Commands
Manuals
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-377
HPMERGEINIT
NM callable only.
Initializes the MERGE/XL subsystem.
Syntax
I32
I32A
PROC
I32A
HPMERGEINIT( status,inputles,preprocessor,outputles,
PROC
32V
I32V
postprocessor,keysonly,numkeys,
I32A CA
PROC
PROC
keys,altseq,keycompare,errorproc,
I32A
I32V
I32A
statistics,memsize,charseq);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPMERGEINIT call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
inputles
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGEINIT is 196.
32-bit signed integer array (optional)
preprocessor
Passes the le identication numbers of the input les to be merged. The last
element of this array should be set to zero. If the les are opened with either
the NOBUF or MR (multirecord) access option, MERGE/XL program performs
the buering and blocking/deblocking.
procedure (reserved)
Do not specify this parameter, but maintain parameter position.
4-378
Command Definitions
HPMERGEINIT
outputles
32-bit signed integer array (optional)
Passes the le identication number of the output le in the rst array
element. If the le is opened with either the NOBUF or MR (multirecord)
access option (aoption ), MERGE/XL performs the buering and
blocking/deblocking.
postprocessor
If you do not specify this parameter, you must call the HPMERGEOUTPUT
intrinsic to retrieve merged records.
procedure (reserved)
keysonly
Do not specify this parameter, but maintain parameter position.
32-bit signed integer by value (optional)
numkeys
Flag that determines if only keys are sent as output. If set to 0, the entire
record is sent as output. If set to any value other than 0, the key elds are
concatenated together with he major key on the left and the remaining keys
following. Default: 0
32-bit signed integer (optional)
keys
Number of keys used during the comparison of records. This parameter can
be either equal to or greater than one. If you specify the numkeys parameter,
you must also specify the keys parameter. Together, numkeys and keys
describe the way records are merged.
32-bit signed integer array (optional)
Passes information about the keys used during the comparison of records. If
you specify the keys parameter, you must specify the numkeys parameter.
Together, keys and numkeys describe the way records are merged.
Command Definitions
4-379
HPMERGEINIT
For each key, there are four entries in the array. The rst element gives the
position of the rst byte of the key within the input record. The second
element gives the number of bytes in the key. The third element indicates the
type of data:
Value
0
1
2
3
4
5
6
7
8
9
10
11
12
13
Meaning
Byte type (ASCII or EBCDIC)
Twos complement (including 16-bit and 32-bit signed integer)
Hewlett-Packard 3000 oating-point format (including real and
long)
IEEE standard oating-point format (32-bit, 64-bit, and
128-bit values)
Packed decimal with odd number of digits
Packed decimal with even number of digits
Display trailing sign
Display leading sign
Display trailing sign separate
Display leading sign separate
Character
Reserved for the operating system
Short oating-point decimal
Floating-point decimal
The fourth element gives the ordering sequence of the records:
Value
0
1
Note
4-380
Meaning
ascending
descending
The integrity of the keys array must be maintained throughout the
MERGE/XL operation. Do not change it until after you have called the
HPMERGEEND intrinsic.
Command Definitions
HPMERGEINIT
altseq
character array (optional)
Passes an alternate collating sequence. The rst element is specied according
to the following table, where the sequence comprises the columns and the data
comprises the rows:
excess space above nonumber table|>
ASCII
ASCII
chr(255)
EBCDIC chr(1)
EBCDIC ALTSEQ
chr(2)
chr(0)
chr(255) undened
The second element species one fewer than the total number of characters in
the collating sequence.
If the rst element is CHR(0), the remaining array elements comprise
the actual collating sequence responsible for the particular MERGE/XL
operation.
keycompare
The defaults are: element 1 = CHR(255), element 2 = CHR(255)
procedure (reserved)
errorproc
Do not specify, but maintain parameter position.
procedure (reserved)
statistics
Do not specify, but maintain parameter position.
32-bit signed integer array (optional)
Returns information on the MERGE/XL operation:
Value
1
2
3
4
5
Meaning
Number of input les
Number of merged records
Number of bytes used for the MERGE/XL work area
CPU time in milliseconds
Elapsed time in milliseconds
Command Definitions
4-381
HPMERGEINIT
memsize
32-bit signed integer by value (reserved)
charseq
Do not specify, but maintain parameter position.
32-bit signed integer array (optional)
Passes language information. Set the rst element to 1 and the second
element to the language ID of the native language collating sequence to be
used for keys of type character (keys parameter equal to 10).
Related Information
Intrinsics
Commands
Manuals
4-382
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
HPMERGEOUTPUT
HPMERGEOUTPUT
NM callable only.
Retrieves records, one at a time, from MERGE/XL.
Syntax
I32 CA I32
HPMERGEOUTPUT(status,buer,length);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPMERGEOUTPUT call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
buer
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGEOUTPUT is 196.
character array (optional)
length
Returns the next output record. The record format is determined by the value
of the keysonly parameter in the HPMERGEINIT intrinsic.
32-bit signed integer by reference (optional)
Returns the length (in bytes) of the buer parameter value. Returns a length
value of -1 when no more records remain.
Related Information
Intrinsics
Commands
Manuals
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-383
HPMERGESTAT
NM callable only.
Prints MERGE/XL statistics on $STDLIST.
Syntax
I32
I32A
HPMERGESTAT( status,statistics);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPMERGESTAT call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
statistics
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGESTAT is 196.
32-bit signed integer array (optional)
Contains the following statistical information about the MERGE/XL
operation:
Number of input les
Number of merged records
Number of bytes used for the MERGE/XL work area
CPU time in milliseconds
Elapsed time in milliseconds
This parameter is returned from the HPMERGEEND intrinsic.
Note
4-384
The statistics array is the same array that was passed to the HPMERGEINIT and
HPMERGEEND intrinsics. It must be referenced by the same name.
Command Definitions
HPMERGESTAT
Operation Notes
Call HPMERGESTAT after you have called the HPMERGEEND intrinsic. A call to HPMERGESTAT
is valid only if you supplied the statistics parameter in the calls to the HPMERGEINIT and
HPMERGEEND intrinsics. The same array is then supplied to HPMERGESTAT .
Related Information
Intrinsics
Commands
Manuals
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-385
HPMERGETITLE
NM callable only.
Prints the version number and title information for MERGE/XL on $STDLIST.
Syntax
I32
HPMERGETITLE(status);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPMERGETITLE call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMERGETITLE is 196.
Operation Notes
HPMERGETITLE prints the date and time produced by the DATELINE intrinsic. You can call
HPMERGETITLE from the program at any time after you have declared the system intrinsics.
Related Information
Intrinsics
Commands
Manuals
4-386
Hewlett-Packard SORT, Hewlett-Packard MERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
HPMYFILE
HPMYFILE
NM callable only. Returns the le name of the native mode program or executable library
(XL) that called the HPMYFILE intrinsic.
Syntax
CA
CA
HPMYFILE(formaldesig,status,length,myle
I32
I32 I32
I32
myle length, myle syntax);
Parameters
formaldesig
character array (required)
Returns the fully qualied MPE syntax le name of the program or XL that
called HPMYFILE.
status
The formaldesig parameter must be at least 28 bytes in length in order
to contain the longest possible MPE syntax le name with delimiters. The
lockword is not returned. The rst and last characters of the returned value
are blanks that act as delimiters.
32-bit signed integer by reference (optional)
HPMYFILE returns a NM Loader 128 error when the rst library name is not
represented using the syntax that the user requires. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMYFILE is 104.
Note
Since HPMYFILE can return information on the success of its execution in the
status parameter, it is good programming practice to specify this parameter
and check its values after the intrinsic call. If an error or warning condition is
encountered and you did not specify the status parameter, HPMYFILE causes
the calling process to abort.
length
32-bit signed integer by reference (optional)
Command Definitions
4-387
HPMYFILE
Returns the length (in bytes) of the le name returned in the formaldesig
parameter (including the two blanks that act as delimiters). A zero returned
indicates that no le name is returned.
character array (optional)
myle
Returns the absolute pathname or fully qualied MPE syntax name of the
program or XL that called HPMYFILE.
myle length
The myle parameter contains the name with delimiters. The rst and last
characters of the returned value are blanks that act as delimiters.
32-bit signed integer by reference (optional)
On input, the myle length parameter species the maximum myle length in
bytes. On output, myle length returns the actual length of myle , including
the surrounding delimiters.
If myle length is not correct upon input, variables allocated near myle can
be overwritten, or an error could occur. If the myle length parameter is not
specied, HPMYFILE determines if the myle parameter is long enough to hold
HPMYFILE to be returned.
myle syntax
Note that a value is not returned in myle length if you do not specify the
myle parameter.
32-bit signed integer by reference (optional)
On input, the myle syntax parameter species the syntax that is used when
HPMYFILE returns name in myle .
On output, the actual syntax is returned in myle syntax . This is only useful
when MPE-escaped syntax is used. The name can be either a MPE syntax
name or a HFS syntax name.
The possible syntaxes are:
0
MPE-escaped syntax
1
MPE-only syntax
2
HFS syntax
The default is MPE-only syntax. Note that if the myle parameter is not
specied, no value is returned in myle syntax .
Operation Notes
You can pass this le name to the HPGETPROCPLABEL intrinsic in the rstle parameter.
HPGETPROCPLABEL searches the les in the binding sequence of its calling process for a
procedure, beginning with the le returned by HPMYFILE.
Related Information
Intrinsics
Commands
Manuals
4-388
None
None
Resource Management Programmer's Guide (32650-90024).
Command Definitions
HPMYPROGRAM
HPMYPROGRAM
NM callable only.
Returns the le name of the program being executed by the calling process.
Syntax
CA
I32 I32
HPMYPROGRAM(formaldesig,status,length
CA
I32
I32
myprogram,myprogram length,myprogram syntax);
Parameters
formaldesig
character array (required)
Returns the fully qualied MPE syntax name of the program being executed
by the calling process.
status
The formaldesig parameter must be at least 28 bytes in length in order
to contain the longest possible MPE syntax le name with delimiters. The
lockword is not returned. The rst and last characters of the returned value
are blanks that act as delimiters.
32-bit signed integer by reference (optional)
HPMYPROGRAM returns a NM Loader error 128 when the program name is not
represented using the syntax that the user species.
Returns the status of the HPMYPROGRAM intrinsic call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPMYPROGRAM is 104.
Command Definitions
4-389
HPMYPROGRAM
length
32-bit signed integer by reference (optional)
myprogram
Returns the length (in bytes) of the le name returned in the formaldesig
parameter (including the two blanks that act as delimiters). A zero returned
indicates that no le name is returned.
character array (optional)
Returns the absolute pathname or fully qualied MPE syntax name of the
program being executed by the calling process.
myprogram length
The myprogram parameter contains the name with delimiters. The rst and
last characters of the returned value are blanks that act as delimiters.
32-bit signed integer by reference (optional)
On input, the myprogram length parameter species the maximum myprogram
length in bytes. On output, myprogram length returns the actual length of
myprogram , including the surrounding delimiters.
If myprogram length is not correct upon input, variables allocated
near myprogram can be overwritten, or an error could occur. If the
myprogram length parameter is not specied, HPMYPROGRAM determines if the
myprogram parameter is long enough to hold HPMYPROGRAM to be returned.
myprogram syntax
Note that a value is not returned in myprogram length if you do not specify
the myprogram parameter.
32-bit signed integer by reference (optional)
On input, the myprogram syntax parameter species the syntax that is
used when HPMYPROGRAM returns the name in myprogram . On output, the
actual syntax is returned in myprogram syntax . This is only useful when
MPE-escaped syntax is used. The name can be either a MPE syntax name or
a HFS syntax name.
The possible syntaxes are:
0
MPE-escaped syntax
1
MPE-only syntax
2
HFS syntax
The default is MPE-only syntax. Note that if the myprogram parameter is
not specied, no value is returned in myprogram syntax .
Operation Notes
The HPMYPROGRAM intrinsic returns the fully qualied le name of the program being executed
by this process. You can pass this name to the HPGETPROCPLABEL intrinsic in the rstle
parameter. HPGETPROCPLABEL searches the les in the binding sequence for a procedure,
beginning with the program le. The program le is the rst le in the binding sequence of
the calling process.
4-390
Command Definitions
HPMYPROGRAM
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
4-391
HPPIPE
Creates a pipe le type object dened as device type of streams, le type of pipes, and record
format of byte streams.
Syntax
HPPIPE(read
I32
I32 I32
fd, write fd, status)
Parameters
read fd
write fd
status
bits (0:16):
bits (16:16):
Caution
4-392
32-bit signed integer by reference (required)
Returns the read le descriptor for the pipe.
le descriptor results in an error.
Attempts to write to a read
32-bit signed integer by reference (required)
Returns the write le descriptor for the pipe. Attempts to read from a
write le descriptor results in an error.
32-bit signed integer by reference (optional)
Returns the status of the HPPIPE call. If no errors or warnings are
encountered, status returns 32-bits of zero. If errors or warnings are
encountered, status if interpreted as two 16-bit elds:
comprise status.info . A negative value indicates an error condition, and a
positive value indicates a warning condition.
comprise status.subsys . The value represents the subsystem that sets the
status information. The subsystem identier for HPPIPE is the le system
subsystem 143.
If an error or warning is encountered and the status parameter was not
specied, HPPIPE causes the calling process to abort.
Command Definitions
HPPIPE
The following status.info values can be returned by HPPIPE:
Table 4-21.
Status
Code
-461
-18
-18
-80
-81
-179
Meaning
Maximum open les for operating system
exceeded.
Bounds violation on read fd parameter.
Bounds violation on write fd parameter.
An internal error occurred.
The operation failed due to a lack of system
resources.
The user lacks the ability to create an
object.
Operation Notes
Enables creation of a pipe, which is a nameless object that can only be reached from members
of its process's family. Returns two le numbers to the calling process that represent the write
and read ends of the pipe. Use the FWRITE and FREAD intrinsics to read and write to the pipe.
Data is returned in a rst in, rst out manner.
Related Information
Intrinsics
Commands
Manuals
FCLOSE, FCONTROL, FFILEINFO and FCHECK
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
4-393
HPRESETDUMP
NM callable only.
Disarms the system debugger call from a process abort.
Syntax
I32
HPRESETDUMP( status);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPRESETDUMP call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPRESETDUMP is 165.
Related Information
Intrinsics
Commands
Manuals
4-394
HPSETDUMP, SETDUMP, RESETDUMP
RESETDUMP
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
HPSELECT
HPSELECT
Determine whether a le or group of les is ready to perform reads, writes, or if it has an
exception condition, and whether to block on one or more of these events if the condition is
not currently true.
Syntax
I16
IV
CA
CA
numselect:=HPSELECT(numles,readmask,writemask,
CA
R
I32
exceptionmask,timeout,status)
Functional Return
numselect
16-bit signed integer (assigned functional return)
Returns a value representing the number of les that have selected true. The
following values are returned:
Value
n
0
-1
Meaning
The number of les that have selected true.
If a timeout value was assigned and the select \timed out".
If an error occurred in the call, an internal error occurred, or if
a soft interrupt occurred before any selected events or before
the time limit expired.
Parameters
numles
integer by value (required)
Passes the number of les (number of les -1) whose bits will be checked by
HPSELECT.
Note that this parameter does not represent the number of les where a bit in
one of the masks is being set. It represents the highest le number (minus 1)
that will be examined by HPSELECT.
Command Definitions
4-395
HPSELECT
readmask
character array by reference (optional)
Species which le numbers will be examined to see if the le that is ready
for reading should be passed. The least signicant bit of each 32-bit word
represents the lowest le number in the word. The rst word contains the bits
for the rst 32 les. Subsequent words contain the bits for additional groups
of 32 les.
For each le number less than numles, the corresponding bit in the mask is
set at return if the bit was set at entry and the le is ready for reading.
Bits representing le numbers greater than numles (minus 1) are ignored.
The buer containing the bit mask only needs to be as large as the number of
32-bit words required to contain the bits fornumles les.
If a timeout is specied and the time limit has elapsed, the mask is cleared on
return.
writemask
Default: No les are checked for reading.
character array by reference (optional)
Species which le numbers are to be examined to see if the le is ready for
writing. The last signicant bit of each 32-bit word represents the lowest le
number in the word. The rst word contains the bits for the rst 32 les.
Subsequent words contain the bits for additional groups of 32 les.
For each le number less than numles, the corresponding bit in the mask is
set at return if the bit was set at entry and the le is ready for writing.
Bits representing le numbers greater than numles (minus 1) are ignored.
The buer containing the bit mask only needs to be as large as the number of
32-bit words required to contain the bits fornumles les.
If a timeout is specied and the time limit has elapsed, the mask is cleared on
return.
Default: No les are checked for writing.
4-396
Command Definitions
HPSELECT
exceptionmask character array by reference (optional)
Species which le numbers are to be examined to see if the le has detected
an exception condition. The last signicant bit of each 32-bit word represents
the lowest le number in the word. The rst word contains the bits for the
rst 32 les. Subsequent words contain the bits for additional groups of 32
les.
For each le number less than numles, the corresponding bit in the mask is
set at return if the bit was set at entry and the le has detected an exception
condition.
Bits representing le numbers greater than numles (minus 1) are ignored.
The buer containing the bit mask only needs to be as large as the number of
32-bit words required to contain the bits fornumles les.
If a timeout is specied and the time limit has elapsed, the mask is cleared on
return.
Default: No les are checked for exception conditions.
timeout
record by reference (optional)
Species a maximum interval to wait for the selection to complete. If a
timeout value of 0 is supplied, HPSELECT checks for the specied conditions,
sets the return mask, and returns without blocking even if none of the
specied conditions are true. If a timeout value is not specied, HPSELECT
waits until an event causes one of the masks to be returned with a non-zero
value.
The timeout value is specied by a 64-bit record containing the following two
elds:
32-bit unsigned integer =
seconds
32-bit integer =
microseconds
Values up to 2**32 seconds can be specied.
Default: HPSELECT blocks until one of the specied conditions is true.
Command Definitions
4-397
HPSELECT
status
32-bit integer by reference (optional)
Returns the status of the HPSELECT call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSELECT is 143.
Possible error values of status.info are:
Value
Meaning
Illegal parameter - the value of numles is negative or an
invalid timeout value was specied.
-18
Bounds violation - one or more parameters point to an invalid
address or to an address the user does not have access to.
-30
Invalid le reference - one or more of the bit masks specied an
invalid le number.
-90
Timeout - the time limit expired before any selected events
occurred.
-91
Soft interrupt - a soft interrupt occurred before any selected
events occurred or before the time limit expired.
No status If status is not passed in, no status is returned.
-9
HPSELECT will not ESCAPE if an error is detected and the status parameter
Note
was not supplied. Errors are also indicated by a -1 in the numselect parameter
(functional return). For assurance of a successful completion, check the
functional return.
The only le type supported by HPSELECT is Net IPC. For all other le types,
HPSELECT always returns TRUE.
Related Information
Intrinsics
Commands
Manuals
4-398
IOWAIT
None
None
Command Definitions
HPSETCCODE
HPSETCCODE
NM callable only.
Sets the condition code for the calling process.
Syntax
I32V
HPSETCCODE( ccodevalue);
Parameters
ccodevalue
32-bit signed integer by value (required)
Sets the condition code for the calling process.
The valid values are:
Value
0
1
2
Meaning
Condition Code Greater Than (CCG). A special condition
occurred but may not have aected the execution of the
request.
Condition Code Less Than (CCL). The request was not
granted because an error condition occurred.
Condition Code Equal (CCE). The request was granted.
Any other values are converted to 1 (CCL).
Operation Notes
The condition code is implemented as two bits associated with each process. From the
condition code value, basic information about what happened during execution of an intrinsic
can be learned.
Although PascalnXL has a built-in function that lets you check the condition code, it does
not allow you to set it. If you write procedures and want to return information through a
condition code, then use the HPSETCCODE intrinsic. It is the only mechanism for setting the
condition code. Only source code compatible routines (implemented in native mode or called
through native mode switch stubs) should call HPSETCCODE.
The HPSETCCODE intrinsic is the only mechanism available for setting the condition code in the
native mode environment.
Command Definitions
4-399
HPSETCCODE
Related Information
Intrinsics
Commands
Manuals
4-400
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPSETDUMP
HPSETDUMP
NM callable only.
Arms the system debugger call from a process abort.
Syntax
I32 CA
HPSETDUMP(status,cmdstr);
Parameters
status
32-bit signed integer (optional)
Returns the status of the HPSETDUMP call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
cmdstr
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSETDUMP is 165.
character array (optional)
An array of characters of up to 255 characters containing the system debugger
commands. The rst character in the buer is recognized as the delimiter.
The last character in the command string must be immediately followed by
that same delimiter.
Command Definitions
4-401
HPSETDUMP
Operation Notes
The process enabling the system debugger can be the current process or any child of the
current process created after the intrinsic call. The commands are contained in a character
array, left-justied, with a delimiting character as the rst and last character of the command
string.
Before a process aborts, Debug is called to execute the commands in cmdstr . Any command
that attempts to obtain user input causes an error when executed by Debug. If the process
that aborts is being run from a job, the process terminates after executing the command
string. If the process is being run from a session, then after the specied command string has
been executed, Debug stops to accept interactive commands with I/O performed at the user
terminal if the following conditions are met: the abort did not occur while in system code;
and the process entered the abort code through a native mode interrupt (typically caused by
arithmetic and code related traps).
Once Debug accepts interactive input, the user is free to enter any DEBUG command. The user
may resume the process or terminate it with the Debug CONTINUE command.
If the abort is caused by a stack overow, a stack trace is printed and the process is
terminated immediately and the command string is not executed.
Related Information
Intrinsics
Commands
Manuals
4-402
HPDEBUG, HPRESETDUMP, RESETDUMP, SETDUMP, STACKDUMP
DEBUG, SETDUMP
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
HPSORTEND
HPSORTEND
NM callable only.
Releases the SORT/XL work area and ends the sorting operation.
Syntax
I32 I32A
HPSORTEND(status,statistics);
Note
HPSORTEND must be called to terminate SORT/XL and release the work space.
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTEND call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
statistics
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTEND is 195.
32-bit signed integer array (optional)
Returns SORT/XL operation information:
Value
1
2
3
4
5
6
Note
Meaning
Number of records sorted
Number of intermediate passes
Number of bytes used for the Hewlett-Packard SORT program
work area
Number of compares
CPU time used in milliseconds
Elapsed time in milliseconds
The statistics array should be the same array that was passed to the
HPSORTINIT intrinsic. It must be referenced by the same name.
Command Definitions
4-403
HPSORTEND
Operation Notes
HPSORTEND initiates the merge phase of the Hewlett-Packard SORT program and writes
to the output le if the HPSORTOUTPUT intrinsic is not used. HPSORTEND is required if you
called HPSORTINIT. Call HPSORTEND either after all calls to the output le are completed by
the HPSORTINIT intrinsic, or after all calls to the HPSORTOUTPUT intrinsic are completed.
HPSORTEND must be called in the same process as the HPSORTINIT intrinsic.
Related Information
Intrinsics
Commands
Manuals
4-404
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
HPSORTERRORMESS
HPSORTERRORMESS
NM callable only.
Retrieves an error message if a fatal error occurs in SORT/XL.
Syntax
I32
CA
I32
HPSORTERRORMESS(status,message,length);
Parameters
status
32-bit signed integer by reference (optional)
Passes the status of a previous HPSORT intrinsic call that failed. The status
value passed in is used to locate the appropriate message catalog entry
associated with the status value. If no errors or warnings were encountered
during the execution of HPSORTERRORMESS, status returns 32 bits of zero. If
errors or warnings are encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
message
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTERRORMESS is 195.
character array (optional)
length
Returns the text of the error message. This parameter may be up to 80
characters long.
32-bit signed integer by reference (optional)
Returns the actual length of the message parameter in characters.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-405
HPSORTINIT
NM callable only.
Initializes the SORT/XL subsystem.
Syntax
I32 I32A
I32A
I32
HPSORTINIT( status,inputles,outputles,outputoption,
I32V
I32V I32V I32A
reclength,numrecs,numkeys,keys
CA
PROC
PROC
I32A
altseq,keycompare,errorproc,statistics,
I32V
I32A
memsize,charseq);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTINIT call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
inputles
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTINIT is 195.
32-bit signed integer array (optional)
Passes the le identication numbers of the input les to be sorted. The last
element of this array should be set to zero. If the les are opened with either
the NOBUF or MR (multirecord) access option (aoption ), the Hewlett-Packard
SORT program performs the buering and blockingndeblocking. $NULL is not
a valid input le.
If this parameter is not used, there must be a call to HPSORTINPUT to supply
records to the Hewlett-Packard SORT program.
4-406
Command Definitions
HPSORTINIT
outputles
32-bit signed integer array (optional)
Passes the le identication number of the output le. The second array
element must be a zero, indicating the end of the array. If the les are
opened with either the NOBUF or MR (multirecord) access option (aoption ), the
SORT/XL program performs the buering and blockingndeblocking.
outputoption
If you do not supply this parameter, you must call HPSORTOUTPUT to retrieve
the sorted records.
32-bit signed integer by value (optional)
Passes a value determining the format of the output records:
Value
0
1
2
3
Meaning
Output record the same as input record (default)
Output record, a 32-bit integer output in binary format, value
is the logical (relative) record number of the record
Output record contains only the key elds, concatenated
together with the major keys on the left, followed by the
remaining keys
Output record is the logical record number (in binary format)
followed by the key elds
reclength
32-bit signed integer by value (optional)
numrecs
Maximum length of a record in bytes. If you do not specify reclength , the
record length is taken from the rst le specied in the inputles parameter.
If you do not specify inputles , you must specify this parameter.
32-bit signed integer by value (optional)
Upper bound to the number of records to be sorted. Use numrecs only if all
input records do not reside on disk. numrecs may be used to determine the
size of the temporary scratch les that SORT builds. The size of the scratch
le(s) that SORT uses is calculated in the following way:
If all records are on disk, the size of the scratch le number is derived from
the current EOF value of the input le and any value supplied for this
parameter is ignored. (If there are multiple input les, then the sum of their
EOFs is used).
numkeys
If all les to be sorted do not reside on disk, or if you do not specify any input
les at all, and you supply this parameter, numrecs will determine the size of
the scratch le(s). Otherwise if you do not supply this parameter, a default
value of 10,000 records per tape le is used.
32-bit signed integer by value (optional)
keys
Number of keys used during the comparison of records. This parameter can
be either equal to or greater than one. If you specify the numkeys parameter,
you must also specify the keys parameter. Together, numkeys and keys
describe the way records are sorted.
32-bit integer array (optional)
Command Definitions
4-407
HPSORTINIT
Passes information about the keys used during the comparison of records. If
you specify the keys parameter, you must specify the numkeys parameter.
Together, keys and numkeys describe the way records are sorted.
For each key, there are four entries in the array. The rst element gives the
position of the rst byte of the key within the input record. The second
element gives the number of bytes in the key. The third element indicates the
type of data:
Value
0
1
2
3
4
5
6
7
8
9
10
11
12
13
4-408
Command Definitions
Meaning
Byte type (ASCII or EBCDIC)
Twos complement (including 16-bit and 32-bit signed integer)
Hewlett-Packard 3000 oating-point format (including real and
long)
IEEE standard oating-point format; (32-bit, 64-bit, and
128-bit values)
Packed decimal with odd number of digits
Packed decimal with even number of digits
Display trailing sign
Display leading sign
Display trailing sign separate
Display leading sign separate
Character
Reserved for the operating system
Short oating-point decimal
Floating-point decimal
HPSORTINIT
The fourth element gives the ordering sequence of the records:
Value
0
1
Meaning
Ascending
Descending
Note
The integrity of the keys array must be maintained throughout the SORT/XL
operation. Do not change it until after you have called the HPSORTEND
intrinsic.
altseq
character array (optional)
Passes an alternate collating sequence. The rst element is specied according
to the following table, where the sequence comprises the columns and the data
comprises the rows:
ASCII
ASCII
chr(255)
EBCDIC chr(1)
EBCDIC ALTSEQ
chr(2)
chr(0)
chr(255) undened
The second element species one fewer than the total number of characters in
the collating sequence.
If the rst element is CHR(0), the remaining array elements comprise the
actual collating sequence responsible for the particular Hewlett-Packard SORT
operation.
keycompare
Default: element 1 = CHR(255),
element 2 = CHR(255)
procedure (reserved)
errorproc
Do not specify this parameter, but maintain parameter position.
procedure (reserved)
Do not specify this parameter, but maintain parameter position.
Command Definitions
4-409
HPSORTINIT
statistics
32-bit signed integer array (optional)
Returns information on the SORT/XL operation:
Value
1
2
3
4
5
6
memsize
Meaning
Number of records sorted
Number of intermediate passes
Number of bytes in the SORT/XL program work area
Number of compares
CPU time used in milliseconds
Elapsed time in milliseconds
32-bit signed integer by value (reserved)
Do not specify, but maintain parameter position.
charseq
32-bit signed integer array (optional)
Passes language information. Set the rst element to 1 and the second
element to the language ID of the native language collating sequence to be
used for keys of type character (keys parameter equal to 10).
Related Information
Intrinsics
Commands
Manuals
4-410
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
HPSORTINPUT
HPSORTINPUT
NM callable only.
Passes records, one at a time, to SORT/XL.
Syntax
I32 CA I32V
HPSORTINPUT(status,buer,length);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTINPUT call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
buer
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTINPUT is 195.
character array (optional)
length
Passes the next input record.
32-bit signed integer by value (optional)
Length of the buer parameter in bytes. This value should be long enough to
contain all specied keys, but not longer than the record size specied in the
reclength parameter of the HPSORTINIT intrinsic.
Operation Notes
Provides an alternative method for supplying input records to SORT/XL. Use this intrinsic
only if the inputles parameter in a call to the HPSORTINIT intrinsic was not used. A call
to HPSORTINPUT follows a call to HPSORTINIT and precedes calls to HPSORTOUTPUT and
HPSORTEND.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-411
HPSORTOUTPUT
NM callable only.
Retrieves records, one at a time, from SORT/XL program.
Syntax
I32
CA I32
HPSORTOUTPUT(status,buer,length);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTOUTPUT call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
buer
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTOUTPUT is 195.
character array (optional)
length
Returns the next output record. The format of this record is as specied in
the outputoption parameter of the HPSORTINIT intrinsic.
32-bit signed integer by reference (optional)
Returns the length of the record parameter value. When no more records
remain, the value of this parameter is set to -1.
Operation Notes
Provides an alternative method for retrieving output records from SORT/XL. HPSORTOUTPUT
puts each output record from SORT/XL into the array specied by the buer parameter. If
the HPSORTINPUT intrinsic was used, HPSORTOUTPUT signals the end of the input process; call
HPSORTOUTPUT only after HPSORTINPUT has passed all records. Use HPSORTOUTPUT only if the
outputles parameter was not specied in the call to HPSORTINIT. A call to HPSORTOUTPUT
always precedes a call to HPSORTEND.
4-412
Command Definitions
HPSORTOUTPUT
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-413
HPSORTSTAT
NM callable only.
Prints the SORT/XL statistics on $STDLIST.
Syntax
I32 I32A
HPSORTSTAT( status,statistics);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTSTAT call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
statistics
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTSTAT is 195.
32-bit signed integer array (optional)
Contains the following statistical information about the SORT/XL operation:
Number of sorted records
Number of intermediate passes
Number of bytes used for the work area
Number of compares
CPU time in milliseconds
Elapsed time in milliseconds
This parameter is returned from the HPSORTEND intrinsic.
Note
4-414
The statistics array should be the same array that was passed to the
HPSORTINIT and HPSORTEND intrinsics. It must be referenced by the same
name.
Command Definitions
HPSORTSTAT
Operation Notes
Call HPSORTSTAT after you have called the HPSORTEND intrinsic. A call to HPSORTSTAT is valid
only if the statistics parameter is specied to the HPSORTINIT and HPSORTEND intrinsics. The
same array is supplied to HPSORTSTAT.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-415
HPSORTTITLE
NM callable only.
Prints the version number and title information for SORT/XL on $STDLIST and prints the
date and time produced by the DATELINE intrinsic.
Syntax
I32
HPSORTTITLE( status);
Parameters
status
32-bit signed integer by reference (optional)
Returns the status of the HPSORTTITLE call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSORTTITLE is 195.
Operation Notes
Call HPSORTTITLE any time after declaring the system intrinsics.
Related Information
Intrinsics
Commands
Manuals
4-416
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
HPSWITCHTOCM
HPSWITCHTOCM
NM callable only.
Makes native mode (NM) to compatibility mode (CM) mixed-mode procedure calls possible.
Syntax
REC I32V
I32V
RECA
HPSWITCHTOCM(proc,method,numparms,parms,
I32V RECV I16
I32
fretlen,fretval,condcode,status);
Parameters
proc
record (required)
Passes the target CM procedure identier, which you can specify either by
a library to search and an ASCII name of up to 16 characters or by a CM
plabel (obtained from the HPLOADCMPROCEDURE or LOADPROC intrinsic).
method
The structure of the proc record varies, depending on how the target
procedure is identied. All variants have a p proc id type eld.
32-bit signed integer by value (required)
Passes a value indicating whether the CM target procedure runs in normal,
split-stack, or no-copy mode. Valid values are:
Value
0
1
2
Note
Meaning
Normal (non-split-stack)
Split-stack
No-copy
If all parameters are within the CM stack or the length of the reference
parameters are less than the threshold, use the normal value. If the reference
parameters are outside of the CM stack (split-stack), wrap the reference
parameters in an extra data segment if the reference parameters are outside of
the CM stack (split-stack method). The no-copy method is the same as the
split-stack method, except that the threshold check is omitted.
Command Definitions
4-417
HPSWITCHTOCM
numparms
32-bit signed integer by value (required)
parms
The number of parameters you are passing to the CM target procedure.
array of records (required)
fretlen
Passes descriptions of each parameter being passed to the CM target
procedure. Each parameter is located and described by a record in this array.
32-bit signed integer by value (optional)
fretval
The length in bytes of the optional functional return value.
record by value (optional)
condcode
NM pointer to the beginning of the area to which the optional functional
return value is returned.
16-bit signed integer by reference (optional)
Returns the condition code that the target CM procedure returns. Valid
values are in the range 0..2.
Note
If a call to HPSWITCHTOCM fails, the value of the condcode parameter becomes
undened. Before attempting to use the condcode , rst check the value of the
status parameter.
status
32-bit signed integer by reference (optional)
Returns the status of the HPSWITCHTOCM intrinsic call. If no errors or warnings
are encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPSWITCHTOCM is 100.
Operation Notes
There are dierences in data and variable representations between NM and CM. Programs
that switch from NM to CM must use the HPSWITCHTOCM intrinsic which provides mixed-mode
execution access and performs the necessary parameter translation between the two modes of
execution.
Related Information
Intrinsics
Commands
Manuals
4-418
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPSWTONMNAME
HPSWTONMNAME
CM callable only.
Allows CM user programs, user libraries, and system code to invoke NM procedures as follows:
Convert CM references in an argument list to virtual NM addresses.
Change the execution mode.
Invoke the NM procedure specied by the CM caller.
Syntax
CA
I16V
CA
I16V
status:= HPSWTONMNAME( procname,proclen,libname,liblen,
I16V
I16 I16
I16V
nparms,arglist,argdesc,functype)
Functional Return
status
I32 (assigned functional return)
Returns a 32-bit integer indicating the status of the call.
Parameters
procname
character array by reference (required)
proclen
Passes the target procedure name. The target procedure must be contained
in an executable library (XL). If the value of procname is invalid, blank, or
does not contain the NM procedure, NL.PUB.SYS is searched.
16-bit signed integer by value (required)
libname
Passes the byte length of the procedure name.
character array by reference (required)
Passes the name of the NM library to be searched. If the value of libname is
invalid, blank or does not contain the NM procedure, NL.PUB.SYS is searched.
Note
By default, the search for the referenced library occurs in the procedure's
group and account. In order to reference a library in some other group
and/or account, you must be sure that libname is a fully qualied name
(name.group.account )
liblen
16-bit signed integer by value (required)
nparms
Passes the byte length of the library name.
16-bit signed integer by value (required)
Command Definitions
4-419
HPSWTONMNAME
arglist
Passes the number of parameters to be passed to the target NM procedure. It
species the length of the argdesc array. Account for any hidden parameters
(for example, parameters, an extensible parameter list, and so forth). For
more information on hidden parameters, refer to the Hewlett-Packard
Pascal/XL Reference Manual (31502-90002).
16-bit signed integer array by reference (required)
argdesc
Passes the actual parameters to be passed in the NM procedure.
16-bit signed integer array by reference (required)
functype
Passes integer codes describing the parameters held in the arglist array. Refer
to Switch Programming Guide (32650-90014) for code descriptions.
16-bit signed integer by value (required)
Passes the data type of the value the target procedure returns if it is a
function. If the target is not a function, the value of this parameter is zero.
Refer to Switch Programming Guide (32650-90014) for possible values.
Operation Notes
Do not use HPSWTONMNAME to invoke a native mode (NM) system supplied intrinsic. The result
of the call may be unpredictable.
NM code can address the entire CM stack, so there is no copying of reference parameters. The
length of each parameter is not needed because lengths are implied in the descriptor list.
Switches by name involve high system overhead on the rst call per name, but substantially
lower overhead on each subsequent call for that name. The HPSWTONMNAME , HPSWITCHTOCM ,
HPLOADCMPROCEDURE, and HPLOADNMPROC intrinsics perform a hashing function on the name of
the other-mode procedure and store the plabel for that procedure in a system internal hash
table. The LOADPROC intrinsic, does not perform hashing and involves high system overhead
each time it is called.
The strings supplied as values of the procname and libname parameters must exactly match
the names of the target NM routine and its NM library, respectively.
By default, the search for the referenced library occurs in the procedure's
group and account. In order to reference a library in some other group
and/or account, you must be sure that libname is a fully qualied name
(name.group.account )
Note
Related Information
Intrinsics
Commands
Manuals
4-420
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPSWTONMPLABEL
HPSWTONMPLABEL
CM callable only.
Allows CM user programs, user libraries, and system code to invoke NM procedures as follows:
Convert CM references in the argument list to virtual NM addresses.
Change the execution mode.
Invoke the NM procedure specied by the CM caller.
Syntax
U32V I16V
I16
I16
status:=HPSWTONMPLABEL(proc,nparms,arglist,argdesc,
I16V
functype);
Functional Return
status
I32 (assigned functional return)
Returns a 32-bit integer indicating the status of the call.
Parameters
proc
32-bit unsigned integer by value (required)
nparms
Passes the NM plabel of the target procedure name. This plabel is usually
obtained by calling the HPLOADNMPROC intrinsic.
16-bit signed integer by value (required)
arglist
Passes the number of parameters to be passed to the target NM procedure. It
species the length of argdesc. Account for any hidden parameters (such as,
parameters, an extensible parameter list, and so forth). For more information
on hidden parameters, refer to the Hewlett-Packard Pascal/XL Reference
Manual (31502-90002).
16-bit signed integer array by reference (required)
argdesc
Passes the actual parameters to be passed to the NM procedure.
16-bit signed integer array by reference (required)
functype
Passes integer codes describing the parameters held in the arglist array (that
is, byte, word, double, pointer, and so forth).
16-bit signed integer by value (required)
Passes the data type of the value the target procedure returns if it is a
function. If the target is not a function, the value of this parameter is zero.
Command Definitions
4-421
HPSWTONMPLABEL
Refer to the Switch Programming Guide (32650-90014) for supported function
types.
Operation Notes
Do not use HPSWTONMPLABEL to invoke a native mode (NM) system supplied intrinsic. The
result of the call may be unpredictable.
NM code can address the entire CM stack, so there is no copying of reference parameters. The
length of each parameter is not required because lengths are implied in the descriptor list.
Related Information
Intrinsics
Commands
Manuals
4-422
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPUNLOADCMPROCEDURE
HPUNLOADCMPROCEDURE
NM callable only.
Unloads a target CM procedure whose plabel is obtained through the HPLOADCMPROCEDURE
intrinsic.
Syntax
CA
U8V
I32
HPUNLOADCMPROCEDURE(procname,library,status);
Parameters
procname
character array (required)
library
Passes as ASCII procedure name, left-justied and padded with blanks. The
name can have a maximum of 16 characters.
8-bit unsigned integer by value (required)
Passes indicator of the CM segmented library to be searched. The valid values
are as follows:
Value
0
1
2
3
4
Meaning
Search the system SL only (default)
Search the logon account SL, then the system SL
Search the logon group SL, then the logon account SL, and
then the system SL
Search the program le's account SL, then the system SL
Search the program le's group SL, then the program le's
account SL, and then the system SL
Command Definitions
4-423
HPUNLOADCMPROCEDURE
status
32-bit signed integer by reference (optional)
Returns the status of the HPUNLOADCMPROCEDURE intrinsic call. If no errors or
warnings are encountered, status returns 32 bits of zero. If errors or warnings
are encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error condition,
and a positive value indicates a warning condition. Refer to the MPE/iX
Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and
32650-90368) for a description of its value.
Bits (16:16) comprise status.subsys . The value represented by these bits
denes the subsystem that set the status information. The subsystem
identier for HPUNLOADCMPROCEDURE is 105.
Operation Notes
Procedures are automatically unloaded when your process terminates. Use the
HPUNLOADCMPROCEDURE intrinsic to unload before the process terminates.
Related Information
Intrinsics
Commands
Manuals
4-424
None
None
Switch Programming Guide (32650-90014)
Command Definitions
HPVOLINFO
HPVOLINFO
Returns volume information.
Up to six items of information can be retrieved. They must be specied in pairs (,itemnum,
item ) and separated by commas
Syntax
I32
I16
*
HPVOLINFO(status, volspeciernum, volspecier
I16
*
[,itemnum, item][...]);
Parameters
status
32-bit integer (optional)
Returns the status of the HPVOLINFO call. If no errors or warnings are
encountered, status returns 32 bits of zero. If errors or warnings are
encountered, status is interpreted as two 16-bit elds.
Bits (0:16) comprise status.info . A negative value indicates an error. A
positive value indicates a warning.
Bits (16:16) comprise status.subsys . This value denes the subsystem that set
the status information. On MPE/iX the volume management identication
number is 163. On MPE V, this eld contains a 0 (zero).
Note
It is good programming practice to specify status and check its value after
the intrinsic call. If you do not specify status and an error condition is
encountered, HPVOLINFO causes the calling process to abort.
Command Definitions
4-425
HPVOLINFO
The error (negative) / warning (positive) values of status.info that can be
returned from a call to HPVOLINFO are given here.
Values marked with an asterisk (*) are returned by the MPE/iX version of
HPVOLINFO only.
Value
0
150
151
152 *
-150
-151
-152
-153
-154
-155
-156
-157
-158
-159
-160
-161
-162
-163
-164
-165
-166
-167
-168
4-426
Command Definitions
Meaning
No errors or warnings (successful call).
Array passed in cannot hold all names|list truncated.
File label is unreadable.
Parts of the set or class are not mounted. Data was gathered
on the portion of the set or class that was mounted, so the
data may be incomplete.
Invalid itemnum .
Missing itemnum or item (not paired).
Required parameter omitted.
Parameter address out of bounds.
Split stack calls not allowed.
LDEV, volume set/class, volume not mounted.
Invalid volume specier number.
Invalid volume specier.
LDEV not a disk LDEV.
Device class not congured for volumes.
Device class does not map into a volume class.
Free space range sizes not in ascending order.
Invalid number of free space ranges specied.
Volume class cannot be specied with system set.
Error while scanning the directory.
Volume label is unreadable.
Disk free space map is bad.
Allocation is disabled for disk free map.
Defective tracks table is unreadable.
HPVOLINFO
Value
-169
-170
-171
-172
-173
-174
-175
-176
-177
-178
-179
-180 *
-181 *
-182 *
-183 *
-184 *
-185 *
-186 *
-187 *
Meaning
Disk I/O error.
Virtual memory is only valid on system volumes.
Directory size is not valid for specied volume.
Spoolles are valid only on system volumes.
Item number is valid only on MPE/iX systems.
Item number is valid only on MPE V systems.
List length specied is invalid.
Item number / volume specier number combination is illegal.
Item is not yet implemented.
Volume table is in an inconsistent state.
Unrecognized drive type.
Physical I/O error.
An unexpected error was detected. Check the error stack to
determine the exact error.
An error was detected in the label management subsystem.
Check the error stack to determine the exact error.
Disk access error. Check the error stack to determine the exact
error.
A mirrored volume that was specied is disabled.
The volume set specied is not a volume set on the system.
The volume class specied is not present in the volume set
specied.
The member volume specied is not present in the volume set
specied.
Command Definitions
4-427
HPVOLINFO
volspeciernum
16-bit signed integer by value (optional)
A 16-bit integer indicating which volume specier is to be used to obtain
information from HPVOLINFO. The default value for volspeciernum is 0 (zero)
if it is not included by the caller. This parameter is used in conjunction with
the volspecier parameter.
The following are the valid volume specier numbers:
Value
0
1
2
3
4
5
volspecier
Meaning
Volume specier is ignored. Using 0 (zero) is the same as
specifying all the volumes on the system.
Volume specier is the logical device number of the volume for
which information is to be obtained.
Volume specier is a volume set name.
Volume specier is a volume set/volume class name pair.
Volume specier is a volume set/volume name pair.
Volume specier is a device class name.
Type varies (optional).
The volspecier is optional when volspeciernum is 0 (zero).
However, for a volspeciernum of 1, 2, 3, 4, or 5, you must specify a
volspecier parameter.
On MPE V, you must declare volspecier as a byte array.
The data type of the volspecier depends on the volspeciernum :
volspeciernum
0
1
2, 3, 4, 5
volspecier
Ignored
16-bit signed integer
Character array
When 0 (zero) is used as the volspeciernum , the volspecier is ignored. A
volspeciernum of 0 (zero) refers to all the volumes on the system. This
includes all system and nonsystem volumes.
When 1 is used as the volspeciernum , the volspecier must be an LDEV
number that corresponds to a congured and mounted volume. An LDEV
number can be any number from 1 through 999.
For character speciers, the rst character determines the delimiter
character for the parameter. The delimiter must be printable; it cannot be
alphanumeric or one of the special characters \. , :" or \_" as explained
below. For example, to pass the volume set MVSN1, you may use % as the
delimiter:
%MVSN1%
4-428
Command Definitions
HPVOLINFO
Operation Notes
For volspeciernum of 3 or 4, the volume set name and the volume class or volume name
must be separated by a colon:
%SET:CLASS%
A colon cannot be used as a delimiter.
Since a volume set or class can be fully qualied on MPE V, periods are allowed in the
name . Because periods and underscores are allowed in an MPE/iX name, these characters
cannot be used as delimiters.
For volspeciernum of 2 or 3 on MPE V (private volumes), a volume set/class name may be
partially or fully qualied:
VSETNAME.GROUP.ACCT
CLASSNAM.GROUP.ACCT
Each eld of the name must consist of one to eight alphanumeric characters. The rst
character must be a letter. The name may have up to 55 characters:
%SETxxxxx.GROUPxxx.ACCOUNTx:CLASSxxx.GROUPxxx.ACCOUNTx%
This name has six 8-character elds, four periods, a colon, and two delimiters. When the
volume set or class name is not fully qualied, it refers to the volume set or class in the
logon group/account.
On MPE/iX, a valid volume set or class name may contain as many as 32 characters.
The rst character must be a letter. The rest may be any combination of alphanumeric
characters, including the underscore \_" and the period \.".
On MPE/iX, the name of the system volume set is MPEXL SYSTEM VOLUME SET.
The system volume set on MPE V does not have a predened name; thus, the name
MPEXL SYSTEM VOLUME SET is used for compatibility with MPE/iX.
On both systems, this is the volume set name returned for items #3 and #12.
When the system volume set name is used on MPE V, it must not be followed by a class
name Refer to the discussion for volspeciernum 5, below)
On MPE V, group and account names cannot be used to partially or fully qualify the set or
volume name when the system volume set name is specied.
For volspeciernum 4 on MPE V, a volume name consists of as many as eight alphanumeric
characters. The rst character must be a letter. For private volumes, names may be
partially or fully qualied (vname.group.acct ). Each eld of the name must be one to eight
alphanumeric characters, the rst of which must be a letter. The maximum number of
characters allowed is 55.
%SETxxxxx.GROUPxxx.ACCOUNTx:NAMExxxx.GROUPxxx.ACCOUNTx%
This name has six 8-character elds, four periods, a colon, and two delimiters.
When the volume name is not fully qualied, it refers to the volume name in the logon
group and/or account.
Command Definitions
4-429
HPVOLINFO
For volspeciernum 4 on MPE/iX, the volume name consists of any string of one to 16
alphanumeric characters, including the underscore and the period. The rst character must
be a letter.
On MPE V, there is no volume class for the system volume set. In order to access a subset
of the system volume set, devices classes are used.
On MPE/iX, volume classes exist for both system and nonsystem volume sets. Volume
classes take the place of device classes.
The volspeciernum 5, for items #6 and #7, provides compatibility between MPE/iX and
MPE V. Specier 5 passes the device class of a group of volumes as they apply to the I/O
conguration. The maximum number of characters allowed in the string is 8. On MPE V,
specier 5 must refer to a device class that is congured to a group of volumes.
ON MPE/iX, when a device class name is specied, a congured and mounted volume class
with the same name must exist in the system volume set. Data is returned based on this
volume class in the system volume set if it exists. Otherwise, an error results.
itemnum
16-bit signed integer by value (optional).
item
This is the cardinal number of the item desired. It species which item value
is to be returned. See Item and Itemnum Pairs.
Type varies (optional).
On MPE V, the item must be declared as a byte array. The actual type of
the item is specied by the corresponding itemnum . See Item and Itemnum
Pairs.
Special Considerations
You do not need special capabilities to use the HPVOLINFO intrinsic.
Split-stack calls are illegal.
When an error is returned, the values in the item parameters are all undened. It is not
guaranteed that the data returned in an item is meaningful if any negative status value is
returned.
On MPE V, real values are accepted from the caller and returned to the caller in 64-bit
Hewlett-Packard 3000 format. This is the default format for MPE V.
On MPE/iX, real values are accepted from the caller and returned to the caller in the
format that is the default mode of the caller.
If the intrinsic is called from compatibility mode, any real values specied to HPVOLINFO
must be in 64-bit Hewlett-Packard 3000 format, and any real values returned by HPVOLINFO
will be in that format.
If the intrinsic is called from native mode, any real values specied to HPVOLINFO must be
in 64-bit IEEE format, and any real values returned by HPVOLINFO will be returned in that
format.
If the system is highly active while this intrinsic is called, some of the item values returned
may not reect the expected results. For example, when HPVOLINFO is called to return the
disk space used by permanent les, a value is returned. But if immediately after the value is
returned, a process on the system purges a le (FCLOSE a le with a disposition of 4), the
value does not reect this dierence.
4-430
Command Definitions
HPVOLINFO
ON MPE V, a set or class is considered to be logically mounted if all of its members are
logically mounted (that is, the LMOUNT or MOUNT command was used).
On MPE/iX, if the volume specier is a set or class, then at least the master volume
must be logically mounted (that is, the volume must be in a master or member state).
If the volume specier is a logical device number, or a volume name, both the volume
specied and the master volume (of the set enclosing the volume specied) must be logically
mounted.
If the volume specier is a logical device number, it must be a member of a set or class
that is logically mounted. If the volume specier is a volume set name, the set must be
logically mounted. If the volume specier is a volume class name, the class must be logically
mounted. If the volume specier is a volume name, that volume must be a member of a set
or class that is logically mounted. When the volume specier is a device class, all of the
logical device numbers in the specied device class must be members of logically mounted
sets/classes. All the volumes on the system, whether they are logically mounted or not, may
be specied by using volspeciernum 0 (zero).
If the volumes for volspeciernum 1, 2, 3, 4, 5 are not logically mounted as specied above,
the HPVOLINFO intrinsic returns a VOLUME NOT MOUNTED error.
If the caller chooses to continue with the same specier, the LMOUNT command (MPE V) or
the VSOPEN command MPE/iX can be used with the COMMAND or HPCICOMMAND intrinsic to
logically mount the appropriate volume sets or classes.
If a volume is taken oine while the intrinsic is accessing it, the process hangs until the
volume is online again. I/Os cannot complete to the disk when a volume is oine.
On MPE/iX, mirrored disks maintain identical copies of the same information on two disks.
Consequently, the values returned by this intrinsic reect information from only one of
the volumes in a mirror disk pair. When retrieving an LDEV number (item #13) using a
volume name that is associated with a mirrored disk pair, only one of the LDEV numbers
of the mirrored pair is returned. Which one is returned is random. Be aware that in this
situation, the LDEV number returned may be dierent across system startups. Later use
of the LDEV numbers returned for mirrored disks are guaranteed to provide accurate
information for the mirrored volume set.
On MPE/iX, if information is requested for the split backup volume set, the information
returned is for the split user volume.
Command Definitions
4-431
HPVOLINFO
Information Returned
INFORMATION RETURNED
Disk space used by permanent les, in sectors
Disk space used by temporary les, in sectors
Drive type
File label overhead, in sectors MPE/iX
Free space area, largest contiguous, in sectors
Free space distribution array
Free space distribution, in sectors per range
Free space, total, in sectors
Logical device number
Member volume names, list
Member volumes, number of
Overhead, directory space, in sectors
Overhead, MPE total, in sectors
Overhead, transaction management MPE/iX
Overhead, transient space, in sectors MPE/iX
Sector size, in bytes
Spoolle disk space usage, in sectors
Transient space, congured maximum, MPE/iX, in sectors
Virtual memory overhead, in sectors MPE V
Volume capacity, in sectors
Volume class names, list
Volume class names, number of
Volume name
Volume sets, list
Volume sets, number of
Volume set name
Volume type
4-432
Command Definitions
ITEM#
32, 33
(reserved: 34, 35 )
8
26, 27
42, 43
36, 37
38, 39
40, 41
13
7
6
24, 25
16, 17
28, 29
18, 19
9
30, 31
20, 21
22, 23
14, 15
5
4
11
3
2
12
10
HPVOLINFO
Item and Itemnum Pairs
All item parameters are passed by reference.
2
Number of volume sets
Function = MPE/iX, MPE V: DSTAT
Returns the number of system and nonsystem volume sets that are congured
on the system. It returns a 32-bit signed integer containing the number of
volumes sets. Zero (0) is the only valid volspeciernum .
May be used with Item =3.
3
List of volume set names
Function = MPE/iX, MPE V: DSTAT
Returns a list of all system and nonsystem volume set names mounted on the
system. The item must be a character array where the list of set names is
returned. The rst four bytes of the array are interpreted as a 32-bit integer
describing the length of the array. The caller must set this value equal to the
maximum number of names that ts into the array being passed. On return,
the value has been modied to reect the actual number of names returned.
The remaining bytes are mapped to a list of 32-byte names.
May be used with Item =2 to determine the maximum number of names that
could be returned.
4
Number of volume classes
Function = MPE/iX: VOLUTIL command
Returns the number of volume classes that a volume or volume set is
associated with. Returns a 32-bit signed integer containing the number
of volume classes. On MPE/iX, this number includes only classes whose
members are logically mounted.
A volume can be associated with more than one volume class. So, when the
specier is 1 or 4, the number returned is the number of volume classes that
the volume is a member of. When the specier is 2, the number returned is
the number of volume classes that are a subset of the volume set.
May be used with Item =5
Command Definitions
4-433
HPVOLINFO
5
List of volume class names
Function = MPE/iX:VOLUTIL
Returns a list of volume class names. On MPE/iX, the list includes only the
names of classes whose members are all logically mounted.
The item must be a character array where the list of class names is returned.
The rst four bytes of the array are interpreted as a 32-bit integer describing
the length of the array. The caller must set this value equal to the maximum
number of names that ts into the array being passed. The remaining
bytes are mapped to a list of 32-byte names. On return, the value has been
modied to reect the actual number of names returned.
A volume can be associated with more than one volume class. So when the
specier is 1 or 4, the list returned is a list of volume classes that the volume
is a member of. When the specier is 2, the list returned is a list of volume
classes that are a subset of the volume set.
May be used with Item =4 to determine the maximum number of names that
could be returned.
6
Number of member volumes
Function = MPE V: LISTVS MPE/iX: VOLUTIL
Returns the number of member volumes in the specied volume set/class or
device class. This item returns a 32-bit signed integer containing the number
of member volumes.
When the specier is 2 or 3, the number of member volumes that make up
the volume set or class is returned, including the master volume in the total
count. When the specier is 5, the number of member volumes congured
with the passed device class is returned.
For example, if a volume set consists of a master volume, MASTER, and two
member volumes, MEMBER1 and MEMBER2, and if the specier used is a volume
set name, the number returned is 3.
On MPE/iX you can remove some or all of the volumes in a volume set
(excluding the master volume). Therefore, this number depends on the
number of volumes you have mounted at the time the intrinsic call is made.
Mirrored disks maintain identical copies of the same information on two disks.
Therefore, the number returned reects only one of the volumes in a mirrored
disk pair. Which volume is chosen is random.
On MPE V, the concept of master and member volumes refers only to private
volumes. Therefore, if the system volume set is specied, the count consists of
the number of volumes that are designated as system volumes.
May be used with Item =7.
7
List of member volume names
Function = MPE/iX: VOLUTIL MPE V: LISTVS
Returns the list of names of the member volumes in the specied volume
set/class or device class.
4-434
Command Definitions
HPVOLINFO
The item must be a character array where the list of member volumes is
returned. The rst four bytes of the array are interpreted as a 32-bit integer
describing the length of the array. The caller must set this value equal to the
maximum number of names that ts into the array being passed. On return,
the value has been modied to reect the actual number of names returned.
The remaining bytes will be mapped to a list of 32-byte names.
Item 6 may be used to determine the maximum number of names that can be
returned.
When the specier is 2 or 3, the list of member volumes that make up the
set or class is returned. When the specier is 5, the list of member volumes
congured with the passed device class is returned.
On MPE/iX, you can remove some or all of the volumes in a volume set
(excluding the master volume). Therefore, this list depends on the number of
volumes you have mounted at the time the intrinsic call is made.
On MPE/iX, a volume class need not include the master volume. As a result,
specier 3 may return a list that does not include the master volume.
On MPE V, the concept of master and member volumes refers only to private
volumes. Therefore, if the system volume set is specied, the count consists of
the number of volumes that are designated as system volumes.
Command Definitions
4-435
HPVOLINFO
8
Drive type
Function = MPE/iX, MPE V: DSTAT
Returns the type of the drive specied. The drive type refers to the name
of the drive (for example: HP7935, HP7937). The character array that is
used must be large enough to contain the longest type string, currently 13
characters.
9
Drive sector size
Returns the logical sector size of the specied drive. This item returns a
32-bit signed integer containing the drive's local sector size in bytes.
Currently, this logical size is 256 bytes. In the future, however, disks may
have dierent physical sector sizes. MPE will map them to system-wide
logical sector sizes.
Volume type
10
This item returns a 32-bit integer specifying the volume type. Valid types are:
1 - System volume
2 - Nonsystem volume
On MPE, there are two types of volume sets: the system volume set and
nonsystem volume sets. A volume from the system volume set is considered a
system volume; a volume from the nonsystem set is considered a nonsystem
volume. A nonsystem set on MPE/iX is equivalent to a private volume set on
MPE V.
Volume name
11
Function = MPE V: VINIT with PLABEL
Returns the volume name of the specied LDEV. This item is a character
array and must be specied with a length of 32 bytes.
12
Volume set name
Function = MPE/iX, MPE V: DSTAT
Returns the volume set name corresponding to the passed LDEV. An LDEV
can be associated with only one volume set. This item is a character array
and must be specied with a length of 32 bytes.
13
Logical device number
Returns the logical device number of the specied volume. This item returns
a 16-bit signed integer containing the logical device number.
14 & 15
On MPE/iX, mirrored disks maintain identical copies of the same information
on two disks. Information is returned for only one of the disks. Which is
returned is random.
Volume capacity
Function = MPE/iX: VOLUTIL command
Returns the volume capacity.
Item 14 returns a 64-bit signed integer containing the volume capacity in
sectors. Item 15 returns the capacity as a 64-bit real.
4-436
Command Definitions
HPVOLINFO
When the specier is 1 or 4, the volume capacity consists of the capacity of
the volume whose LDEV or volume name was specied.
16 & 17
When the specier is 2 or 3, the capacity of the volumes that make up the
volume set or class are totalled. This total value is returned.
Total MPE overhead
Returns the total MPE overhead, which consists of everything on a volume
that is not set aside for le space use. This is the volume space used for
operating system purposes.
Item 16 returns a 64-bit signed integer containing the total MPE overhead.
Item 17 returns the overhead as a 64-bit real.
Files that compose the code for the operating system are not included in this
overhead. Some of the space that is considered overhead includes:
MPE V - volume label, virtual memory, directory, defective tracks/sectors
table, initial segments, disk coldload information table, volume table, free
space map, and channel programs.
MPE/iX - volume label, le label table, directory, volume set information
table, free space map, transient space, and transaction management overhead.
A subset of the overhead is returned through itemnum s 18 through 29:
18 & 19 - MPE transient space
20 & 21 - MPE/iX congured transient space
22 & 23 - MPE V virtual memory
24 & 25 - Directory
26 & 27 - MPE/iX le label tables
28 & 29 - MPE/iX transaction management
When the specier is 1 or 4, the total MPE overhead consists of the MPE
overhead on the volume whose LDEV or volume name was specied. These
are subsets of items 16 and 17.
18 & 19
When the specier is 2 or 3, the MPE overhead on the volumes that make up
the set or class is returned.
MPE/iX transient space overhead
Returns the MPE/iX transient space overhead. This item is valid only on
MPE/iX.
These are subsets of items 16 and 17.
Item 18 returns a 64-bit signed integer containing the transient space
overhead in sectors. Item 19 returns this overhead as a 64-bit real.
Transient space overhead consists of volume space that is used for temporary
processes, such as stacks, heaps, and the operating system data structure.
When the specier is 1 or 4, the transient space consists of the transient space
on the volume whose LDEV or volume name was specied.
Command Definitions
4-437
HPVOLINFO
20 & 21
When the specier is 2 or 3, the transient space on the volumes that make up
the set or class is returned.
Congured maximum MPE/iX transient space
Function = MPE/iX: VOLUTIL command
Returns the congured maximum MPE/iX transient space.
These are subsets of items 16 and 17.
Item 20 returns a 64-bit signed integer containing the maximum transient
space overhead in sectors. Item 21 returns this overhead as a 64-bit real.
This is volume overhead that is congured for transient space use. It is not
necessarily used. This is space congured for stacks, heaps, and operating
system structures.
Refer to Items 18 and 19 above.
When the specier is 1 or 4, the congured maximum transient space consists
of the congured transient space on the volume whose LDEV or volume name
was specied.
When the specier is 2 or 3, the congured transient space on the volumes
that make up the volume set or class is returned.
22 & 23
MPE V virtual memory overhead
Function = MPE V: SYSDUMP virtual memory device allocation portion (SM
capability required to use SYSDUMP).
Returns the MPE virtual memory overhead. This is valid only on MPE V.
These are subsets of items 16 and 17.
Item 22 returns a 64-bit signed integer containing the virtual memory
overhead in sectors. Item 23 returns this overhead as a 64-bit real.
MPE V virtual memory overhead is the volume space that is allocated for
saving segments of main memory temporarily. This amount of congured
virtual memory space is equivalent to the amount of used virtual memory
space. Virtual memory on MPE V is allocated only on system volumes. There
is no virtual memory on private volumes.
When the specier is 1 or 4, the virtual memory overhead consists of the
virtual memory on the volume whose LDEV or volume name was specied.
When the specier is 2, the only valid specier is MPEXL_SYSTEM_VOLUME_SET.
This is because virtual memory is allocated only on system volumes.
Specier 3 is invalid. This is because virtual memory is valid only on the
MPE V system volume set, and because the concept of volume classes does
not hold for MPE V system volumes.
24 & 25
Directory space overhead
Returns the directory space overhead.
Item 24 returns a 64-bit signed integer containing the directory space
overhead in sectors. Item 25 returns this overhead as a 64-bit real.
4-438
Command Definitions
HPVOLINFO
These are subsets of items 16 and 17.
Directory space is area on system and nonsystem volumes reserved for
accounting information. It consists of the directory space used for permanent
les.
When the specier is 1 or 4, the directory space overhead consists of the
directory space on the volume whose LDEV or volume name was specied.
When the specier is 2 or 3, the directory space overhead on the volumes that
make up the volume set or class is returned.
26 & 27
On MPE V, the system directory is allocated on LDEV 1, and for private
volumes, the directory is allocated on the master volume of the volume set or
class. Specifying a volume set or class gives the same results as specifying the
master volume of the set or class.
MPE/iX le label overhead
Returns the MPE/iX le label overhead. This item is valid only on MPE/iX.
Item 26 returns a 64-bit signed integer containing the le label overhead in
sectors. Item 27 returns this overhead as a 64-bit real.
These are subsets of items 16 and 17.
On MPE/iX, each volume has its own label table, which contains le labels
and extent descriptors for les that begin on that volume.
When the specier is 1 or 4, the le label overhead consists of the overhead on
the volume whose LDEV or volume name was specied.
28 & 29
When the specier is 2 or 3, the le label overhead on the volumes that make
up the set or class is returned.
MPE/iX transaction management overhead
Returns the MPE/iX transaction management overhead. This item is valid
only on MPE/iX.
Item 28 returns a 64-bit signed integer containing the transaction
management overhead in sectors. Item 29 returns this overhead as a 64-bit
real.
These are subsets of items 16 and 17.
Transaction management overhead consists of any logging information that is
maintained in order to provide le consistence and le recovery.
When the specier is 1 or 4, the transaction management overhead consists
of any logging information kept on the volume whose LDEV or volume name
was specied.
When the specier is 2 or 3, the transaction management overhead on the
volumes that make up the set or volume class is returned.
Command Definitions
4-439
HPVOLINFO
30 & 31
Spoolle disk space usage
Function = MPE/iX, MPE V: SHOWOUT
Returns the MPE spoolle disk space usage.
Item 31 returns a 64-bit signed integer containing the spoolle disk space
usage in sectors. Item 32 returns this usage as a 64-bit real.
Spoolle space consists of the volume space that is used by hidden spoolles.
Hidden spoolles are not part of the permanent le space. This space can be
found only on system volumes that are congured with the device class SPOOL.
Spool le space is not allocated on nonsystem volumes.
When the specier is 1 or 4, the spoolle space consists of the space used on
the volume whose LDEV or volume name was specied.
When the specier is 2, the volume set name must refer to the system volume
set name.
Specier 3 is valid only on MPE/iX.
32 & 33
Disk space used by permanent les
Function = MPE/iX, MPE V:REPORT @.@
Returns the disk space used by permanent les.
Item 32 returns a 64-bit signed integer containing the disk space used by les
in sectors. Item 33 returns this space as a 64-bit real.
When the specier is 1 or 4, the disk space used by les consists of the space
used by permanent les on the volume whose LDEV or volume name was
specied.
When the specier is 2 or 3, the disk space used by permanent les on the
volumes that make up the volume set or class is returned.
34 & 35
36 & 37
Reserved for disk space used by temporary les.
Free space distribution array
Function = MPE/iX: DISCFREE MPE V: FREE5
Returns the free space distribution array. The caller passes an array that
species a series of ranges. The intrinsic returns the number of free areas
whose size is within each of the specied ranges. The array must consist of
64-bit values.
The item passed must be a variable length array of 64-bit numbers (maximum
array length of 16 elements).
For item 36, the values must be in integer format. It returns an array of
64-bit integers containing the free space distribution.
For item 37, the values must be in real format. Real values is rounded o. It
returns an array of 64-bit reals.
On MPE V, the largest value that may be specied in either format is
2,147,483,646.
4-440
Command Definitions
HPVOLINFO
The rst value is the number of ranges (minimum 2, maximum 16). The
remaining values are the lower bounds for the ranges, in ascending order. On
return the rst element is the number of free areas whose size is smaller than
the smallest bound specied. Each remaining element is the number of free
space areas whose size is greater than or equal to the bound, and less than the
next larger bound. The following example shows a return in six ranges:
Array Values
Free Area Size Ranges
Index Passed In
1
2
3
4
5
6
6
1 - 9
10
10 - 99
100
100 - 999
1000
1000 - 9999
10000 10,000 - 99,999
100000 100,000+
contiguous
contiguous
contiguous
contiguous
contiguous
contiguous
sectors
sectors
sectors
sectors
sectors
sectors
For example, if there are four areas of free space that are between the size of
100 and 999, the third value of the free space distribution array would contain
4 on return.
Notice that the number of ranges specied in the rst element of the array
example is 6, but only 5 lower bounds are specied, because the smallest lower
bound is assumed to be 1 (one).
When the specier is 1 or 4, the free space distribution array consists of the
contiguous free space areas on the volume whose LDEV or volume name was
specied.
38 & 39
When the specier is 2 or 3, the free space distribution array returns the total
values from the volumes that make up the volume set or class.
Free space distribution sectors per range
Function = MPE/iX: DISCFREE, MPE V: FREE5
Returns the free space distribution sectors per range.
The caller passes an array that species a series of ranges. For each range
specied in the array, the intrinsic returns the total free space for free areas
found in that range.
Refer to Items 36 and 37 for the format of the free space distribution array
passed to the intrinsic and for the format of the returned array.
40 & 41
Total free space
Function = MPE/iX: DISCFREE , MPE V: FREE5
Returns the total free space on a volume or a group of volumes.
Item 40 returns a 64-bit signed integer containing the total free space in
sectors.
Item 41 returns a 64-bit real.
When the specier is 1 or 4, the total free space consists of the total free
space on the volume whose LDEV or volume name was specied.
Command Definitions
4-441
HPVOLINFO
42 & 43
When the specier is 2 or 3, the total free space on the volumes that make up
the volume set or class is returned.
Largest contiguous free space area
Function = MPE/iX: DISCFREE , MPE V: FREE5
Returns the largest contiguous free space area on a volume or a group of
volumes.
Item 42 returns a 64-bit signed integer containing the largest contiguous free
space area in sectors.
Item 43 returns a 64-bit real.
When the specier is 1 or 4, the largest contiguous free space consists of the
largest contiguous free space on the volume whose LDEV or volume name was
specied.
When the specier is 2 or 3, the largest contiguous free space on the volumes
that make up the volume set or class is returned.
For example, for speciers 2 or 3, if a volume set is composed of LDEVs 2,
3, and 4, and the largest contiguous free space on these volumes are 37785,
56528, and 56171, respectively, the value returned is 56528.
4-442
Command Definitions
HPVOLINFO
Variable Conventions
Convention
Meaning
I16
I32
I64
R64
CA
I64A
R64A
ITEM#
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
16-bit signed integer
32-bit signed integer
64-bit signed integer
64-bit signed real
Character array
64-bit signed integer array
64-bit signed real array
ITEM
Number of volume sets
List of volume set names
Number of volume classnames
List of volume class names
Number of member volumes
List of member volume names
Drive type
Sector size in bytes
Volume type
Volume name
Volume set name
Logical device number
Volume capacity in sectors
Volume capacity in sectors
Total MPE overhead in sectors
Total MPE overhead in sectors
MPE/iX transient space overhead in
sectors
TYPE
APPLICABLE
VOLUME
SPECIFIERS
I32
CA
I32
CA
I32
CA
CA
I32
I32
CA
CA
I16
I64
R64
I64
R64
I64
0
0
1, 2, 4
1, 2, 4
2, 3, 5
2, 3, 5
1, 4
1, 4
1, 4
1
1
4
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
Command Definitions
4-443
HPVOLINFO
ITEM#
ITEM
TYPE
APPLICABLE
VOLUME
SPECIFIERS
19
MPE/iX transient space overhead in
sectors
Congured maximum MPE/iX transient
space in sectors
Congured maximum MPE/iX transient
space in sectors
MPE V virtual memory overhead in
sectors
MPE V virtual memory overhead in
sectors
Directory space overhead in sectors
Directory space overhead in sectors
MPE/iX le label overhead in sectors
MPE/iX le label overhead in sectors
MPE/iX transaction management
overhead
MPE/iX transaction management
overhead
Spoolle disk space usage in sectors
Spoolle disk space usage in sectors
Disk space used by permanent les in
sectors
Disk space used by permanent les in
sectors
(Reserved for) Disk space used by
temporary les in sectors
(Reserved for) Disk space used by
temporary les in sectors
Free space distribution array
Free space distribution array
Free space distribution sectors per range
R64
1, 2, 3, 4
I64
1, 2, 3, 4
R64
1, 2, 3, 4
I64
1, 2, 4
R64
1, 2, 4
I64
R64
I64
R64
I64
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
R64
1, 2, 3, 4
I64
R64
I64
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
R64
1, 2, 3, 4
I64
1, 2, 3, 4
R64
1, 2, 3, 4
I64A
R64A
I64A
1, 2, 3, 4
1, 2, 3, 4
1, 2, 3, 4
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
4-444
Command Definitions
HPVOLINFO
ITEM#
ITEM
TYPE
39
40
41
42
Free space distribution sectors per range
Total free space in sectors
Total free space in sectors
Largest contiguous free space area in
sectors
Largest contiguous free space area in
sectors
R64A
I64
R64
I64
43
R64
APPLICABLE
VOLUME
SPECIFIERS
1, 2,
1, 2,
1, 2,
1, 2,
3, 4
3, 4
3, 4
3, 4
1, 2, 3, 4
Command Definitions
4-445
INITUSLF
NM and CM callable.
Initializes a buer corresponding to record 0 of a USL le to the empty state.
A USL contains CM object code and is meaningful only in the CM program
development process.
Note
Syntax
I16
I16V
I16A
uslferror:=INITUSLF(uslfnum,record);
Functional Return
uslferror
16-bit signed integer (assigned functional return)
Returns error information. If no error occurs, no value is returned. If an error
occurs (condition code returns CCL (1)), one of the following is returned:
Value
0
1
3
Meaning
An unexpected end-of-le was encountered when writing to
uslfnum .
Unexpected I/O error occurred.
Your request attempted to exceed the maximum le size
(32,768 records) or was smaller than the minimum le size (4
records).
Parameters
uslfnum
16-bit signed integer by value (required)
record
The le number of the USL le.
16-bit signed integer array (required)
Passes and returns a buer, corresponding to the rst record of the USL le
(record 0), to be initialized to the empty state. Set this 128-element array to
all zeros. The intrinsic sets certain values in record 0 before returning to the
calling program.
4-446
Command Definitions
INITUSLF
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An error number is returned to uslferror .
Related Information
Intrinsics
Commands
Manuals
None
None
MPE Segmenter Reference Manual (30000-90011)
Command Definitions
4-447
IODONTWAIT
NM and CM callable.
Initiates completion operations for an I/O request.
Syntax
I16
I16V
UDS I16
U16
fnum:=IODONTWAIT(filenum,buer,length,cstation)
Functional Return
fnum
16-bit signed integer (assigned functional return)
The le number for which the completion occurred. If no completion
occurred, zero is returned.
Parameters
lenum
16-bit signed integer by value (required)
buer
The le number for which there is a pending I/O request. If you specify 0, the
IODONTWAIT intrinsic checks for any I/O completion.
user-dened structure (optional)
length
Passes an input buer. This buer must be large enough to contain the input
record. It should be the same buer specied in the original I/O request if
that was a read request. This allows for a proper recognition of EOF where
applicable. The buer parameter is required if not in priviledged mode, or the
buer parameter can be ommitted if the GETPRIVMODE intrinsic is called
rst.
16-bit signed integer by reference (optional)
cstation
Returns the length of the received or transmitted record. If the original
request specied a byte count, the integer represents bytes; if the request
specied half words, the integer represents half words. This parameter is
pertinent only if the original I/O request was a read request. The FREAD
intrinsic always returns zero as its functional return if you specify nowait I/O.
In this case, the actual record length is returned in the length parameter of
IODONTWAIT.
16-bit unsigned integer by reference (optional)
Returns the number of the calling station when completed (used for
distributed systems).
(ASC) Not used for asynchronous devices.
4-448
Command Definitions
IODONTWAIT
Operation Notes
The IODONTWAIT intrinsic operates the same as IOWAIT with one exception: if you call IOWAIT
and no I/O has completed, then the calling process is suspended until some I/O completes;
if you call IODONTWAIT and no I/O has completed, then control is returned to the calling
process. (CCE (2) is returned and the result of IODONTWAIT is zero.)
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. If the functional return is not zero, then I/O completion
occurred with no errors. If the functional return is zero, no I/O has
completed.
An end-of-le was encountered.
Request denied. Normal I/O completion did not occur; there were no I/O
requests pending, a parameter error occurred, or an abnormal I/O completion
occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Interprocess Communication Programmer's Guide (32650-90019)
Command Definitions
4-449
IOWAIT
NM and CM callable.
Initiates completion operations for an I/O request.
Syntax
I16
I16V
UDS
I16
U16
fnum:=IOWAIT(lenum,buer,length,cstation);
Functional Return
fnum
16-bit signed integer (assigned functional return)
The le number for which the completion occurred. If no completion
occurred, zero is returned.
Parameters
lenum
16-bit signed integer by value (required)
buer
The le number for which there is a pending I/O request. If you specify 0, the
IOWAIT intrinsic waits for the rst I/O completion.
user-dened structure (optional)
length
Passes an input buer. This buer must be large enough to contain the input
record. It should be the same buer specied in the original I/O request if
that was a read request. This allows for proper recognition of EOF where
applicable. The buer parameter is required if not in priviledged mode, or the
buer parameter can be ommitted if the GETPRIVMODE intrinsic is called
rst.
16-bit signed integer by reference (optional)
cstation
Returns the length of the received or transmitted record. If the original
request specied a byte count, the integer represents bytes; if the request
specied half words, the integer represents half words. This parameter is
pertinent only if the original I/O request was a read request. The FREAD
intrinsic always returns zero as its functional return if you specify nowait I/O.
In this case, the actual record length is returned in the length parameter of
IOWAIT.
16-bit unsigned integer by reference (optional)
Returns the number of the calling station when completed (used for
distributed systems).
(ASC) Not used for asynchronous devices.
4-450
Command Definitions
IOWAIT
Operation Notes
The IOWAIT intrinsic initiates completion operations for an I/O request. If you opened a le
with the nowait I/O mode aoption of the FOPEN/HPFOPEN intrinsic (aoption bit (4:1) = 1),
calls to either the IOWAIT or IODONTWAIT intrinsic must follow all read and write requests.
This intrinsic initiates completion operations for the associated I/O request, including data
transfer into your buer area if necessary.
The IOWAIT intrinsic call must precede any subsequent I/O request against the le. Within
this restriction, you can delay the IOWAIT intrinsic call as long as desired to allow eective I/O
and processing overlap.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. I/O completion occurred with no errors.
An end-of-le was encountered.
Request denied. Normal I/O completion did not occur, because there were
no I/O requests pending, a parameter error occurred, or an abnormal I/O
completion occurred.
Related Information
Intrinsics
Commands
Manuals
None
None
Interprocess Communication Programmer's Guide (32650-90019)
Command Definitions
4-451
JOBINFO
NM and CM callable.
Returns information about any current job or session under your user name and account. If
you have sucient capabilities, it returns information about jobs or sessions running under
other users and accounts.
Syntax
I16V I32 U16A
JOBINFO(jsind,jsnum,jsstatus
I16V
*
I16
[,itemnum,item,itemerror] [...]);
You can specify up to ve itemnum /item /itemerror triples.
Note
Parameters
jsind
16-bit signed integer by value (required)
Indicates whether jsnum denotes a session or job:
Value
1
2
jsnum
Meaning
jsnum is a session
jsnum is a job
32-bit signed integer by reference (required)
Passes the job/session number for which information is requested. Job/session
numbers can be displayed by the SHOWME and SHOWJOB commands. If this
value is zero, JOBINFO returns information about your logon job/session
(unless the rst itemnum has a value of 1; see below). When you pass a 0 for
jsnum, JOBINFO returns the actual job/session number in jsnum.
4-452
Command Definitions
JOBINFO
jsstatus
16-bit unsigned integer array (required)
Returns indicator of the success or failure of the call in a two-element array.
The rst element contains the error indicator. The second element should be
ignored.
Value
0
1
2
3
4
5
Meaning
Successful call. All itemerrors equal zero.
Partially successful call. One or more itemerror(s) returned
with nonzero values.
Unsuccessful call. All itemerrors returned with nonzero values.
Unsuccessful call. Syntax error in calling sequence.
Unsuccessful call. Unable to retrieve jsnum .
Process terminated. The process terminated during the start of
retrieval.
itemnum
16-bit signed integer by value (optional)
item
Species which item value is to be returned. Refer to Table 4-20 for a
complete list of valid item numbers and what they return to the caller.
type varies (optional)
A reference parameter (whose data type corresponds to the data type for the
desired information) to which the desired information is returned.
These are standard data types and are dened in Table 2-1. All itemnum and
item parameters are output parameters. The only exception is itemnum =1,
when all the following conditions are met:
The caller passes itemnum=1 in the rst item triple.
The item parameter contains a character string of the form
[jsname ,]username.acctname .
The jsnum parameter is set to 0, and the jsind parameter is set to 1 or 2.
If all these conditions are met, JOBINFO returns information about the
specied job/session in all other items and returns that job/session number in
jsnum. The size of the rst item is determined by the way it is used.
Command Definitions
4-453
JOBINFO
itemerror
16-bit signed integer by reference (optional)
Returns the success or failure of the retrieval of each item. The returned
values are:
Value
0
1
2
3
4
Meaning
Successful
Invalid itemnum
Information requested not valid for specied jsnum
Insucient capability
Information not available
Table 4-22. JOBINFO Itemnum/Item Values
Itemnum Mnemonic
1
CA
Item Description
[jsname,]user.account.
Can be used as an I/O parameter:
If used as an input parameter, the array must be 26 bytes long, plus one for a
binary 0 (zero) terminator. The input string must be in the form
[jsname,]user.account . The wildcard character @ is not allowed.
If used as an output parameter, the array must be 26 bytes long. The output is
left-justied and padded with blanks.
2
CA8
Session/job name.
An ASCII output parameter. Output is left-justied and padded with blanks.
3
CA8
User name.
An ASCII output parameter. Output is left-justied and padded with blanks.
4
CA8
User logon group.
An ASCII output parameter. Output is left-justied and padded with blanks.
5
CA8
User account.
An ASCII output parameter. Output is left-justied and padded with blanks.
6
CA8
User home group.
An ASCII output parameter. Output is left-justied and padded with blanks.
7
I32
The date/time that is displayed by the :SHOWJOB command. This date/time is
updated whenver a job changes state (SCHED, WAIT, EXEC).
Returns a 32-bit signed integer to be used by the FMTCLOCK intrinsic. For a job,
this is the time it enters the WAIT state.
4-454
Command Definitions
JOBINFO
Table 4-22. JOBINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
8
U16
Item Description
The date/time that is displayed by the :SHOWJOB command. This date/time is
updated whenever a job changes state (SCHED, WAIT, EXEC).
Returns a 16-bit unsigned integer to be used by the FMTCALENDAR intrinsic. For a
job, this is the date when it enters the WAIT state.
9
CA8
Input LDEV/class name.
An ASCII output parameter. Whatever array the user passes in will be
overwritten with the LDEV/class name, using exactly the number of characters
in the LDEV/class name. The remainder of the array is left intact; no ll
character is used.
10
CA8
Output LDEV/class name.
An ASCII output parameter. Whatever array the user passes in will be
overwritten with the LDEV/class name, using exactly the number of characters
in the LDEV/class name. The remainder of the array is left intact; no ll
character is used.
11
CA
Current job step.
Returns a maximum of 238 ASCII characters and is the image of the command
currently executing. The array must be long enough for the expected command
image (the length can be obtained from itemnum =34).
12
I16
Current number of active jobs
13
I16
Current number of active sessions
14
I16
Job input priority
15
I32
Job/session number
16
I16
Jobfence
17
I16
Job output priority
18
I16
Number of copies
19
I16
Job limit (system)
20
I16
Session limit (system)
21
I16
Job deferred. Returns the values:
0
1
No
Yes
22
U16
Main CI PIN for job/session
23
U16
Original job spooled.
Returns the values:
0
1
No
Yes
Command Definitions
4-455
JOBINFO
Table 4-22. JOBINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
24
U16
Item Description
RESTART option.
Returns the values:
0
1
25
U16
No
Yes
Sequenced job.
Returns the values:
0
1
26
U16
No
Yes
Term code.
Returns the values:
0
1
Regular terminal
Regular terminal with special logon
27
U16
CPU limit
28
U16
Session/job state.
Returns the values:
2
4
32
48
56
Executing
Suspending
Wait
Initialization
Scheduled
29
U32
User's local attributes
30
I16
$STDIN spoolle number.
Returns data for current jobs and sessions only. Valid for spoolle numbers less
than or equal to 32768.
31
I16
$STDIN spoolle status.
Returns data for current jobs and sessions only. Returns the values:
0
1
3
4
32
I16
Open
Active
Reserved
Ready
$STDLIST spoolle number.
Returns data for current jobs and sessions only. Valid for spoolle numbers less
than or equal to 32768.
4-456
Command Definitions
JOBINFO
Table 4-22. JOBINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
33
I16
Item Description
$STDLIST spoolle status.
Returns data for current jobs and sessions only. Returns the values:
0
1
2
3
Active
Ready
Open
Reserved
34
I16
Length of itemnum =11 (current job step)
35
U16
SET STDLIST=DELETE invoked. Returns the values:
0
1
$STDLIST is saved
SET STDLIST=DELETE is invoked
36
U16
Job information table data segment number
37
N/A
Not allowed. Call results in error to calling routine
38
I32
$STDIN spoolle number.
Returns data for current jobs and sessions only. Valid for all spoolle numbers
regardless of size.
39
I32
$STDLIST spoolle number.
Returns data for current jobs and sessions only. Valid for all spoolle numbers
regardless of size.
40
U16
Session quiet mode.
Returns:
0
1
No
Yes
41
I32
The job or session number of the job submitter.
42
CA8
The job or session name of the job submitter.
An ASCII output parameter. Output is left justised and padded with blanks.
43
CA8
The user name of the job submitter.
An ASCII output parameter. Output is left justied and padded with blanks.
44
CA8
The user account of the job submitter.
An ASCII output parameter. Output is left justied and padded with blanks.
45
CA8
The logical device of the job submitter.
An ASCII output parameter. Output is left justied and padded with blanks.
Command Definitions
4-457
JOBINFO
Table 4-22. JOBINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
46
U16
Item Description
The date/time that the STREAM command was submitted by the job submitter.
For jobs, this is the date that the job was streamed (and is the same date that
appears in the job submitter banner.) For sessions, this is the date that the
session was started via either the STARTSESS command, the STARTSESS intrinsic,
or by the default automatic logon at boot time.
This item value diers from item 8 only for jobs scheduled for the future.
Returns a 16-bit unsigned integer to be used by the FMTCALENDAR intrinsic.
47
I32
The date/time that the STREAM command was submitted by the job submitter.
For jobs, this is the time that the job was streamed (and is the same time that
appears in the job submitter banner.) For sessions, this is the date that the
session was started via either the STARTSESS command, the STARTSESS intrinsic,
or by the default automatic logon at boot time.
This item value diers from item 7 only for jobs scheduled for the future.
Returns a 32-bit signed integer to be used by the FMTCLOCK intrinsic.
48
U16
The job or session type of the job submitter.
Unless otherwise indicated, all mnemonics are as dened in Table 2-1.
Note
Operation Notes
System manager (SM) or account manager (AM) capability is required to retrieve information
about jobs and sessions not logged under your user and account. AM capability restricts
access to account session and job information; SM capability allows access to all session and
job information. This intrinsic does not alter the condition code.
Related Information
Intrinsics
Commands
Manuals
4-458
JOBINFO
SHOWJOB, SHOWME, SHOWOUT, SHOWIN
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
KILL
KILL
NM and CM callable.
Deletes a child process of the calling process and all of its descendants. Process handling (PH)
capability is required.
Syntax
I16V
KILL(pin);
Parameters
pin
16-bit signed integer by value (required)
Passes the process identication number (PIN) of the child process to be
deleted.
Operation Notes
All resources held by the deleted processes are released. Any remaining les opened by the
deleted processes are closed and assigned the same disposition they had when opened.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request granted. The specied process is already being terminated.
Request denied. An illegal PIN was specied.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-459
LOADPROC
NM and CM callable.
Dynamically loads a compatibility mode (CM) segmented library (SL) procedure and any
external procedures it has referenced.
Syntax
I16
CA
I16V
I16
idnum:=LOADPROC(procname,library,plabel);
Functional Return
idnum
16-bit signed integer (assigned functional return)
Returns an identity number required by the UNLOADPROC intrinsic to unload
the CM SL procedure dynamically. If a loader error occurs (condition code
returns CCL (1)), the identity number represents a CM loader error number.
Parameters
procname
character array (required)
library
Passes the name of the procedure to be loaded. The procedure name must
be terminated with a blank and be <= 15-characters; excess characters
are truncated without a warning message and any procedure matching the
truncated name is loaded.
16-bit signed integer by value (required)
Passes a value requesting a library search for the procedure residing in your
logon group:
Value
0
1
2
3
4
plabel
4-460
Meaning
Search system SL only
Search logon account SL, then system SL
Search logon group SL, logon account SL, then system SL
Search program le's account SL, then system SL
Search program le's group SL, program le's account SL, and
then system SL
16-bit signed integer by reference (required)
Returns the procedure's label. This is the external CM plabel.
Command Definitions
LOADPROC
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The value returned to idnum is a CM loader error code.
Related Information
Intrinsics
Commands
Manuals
None
None
Switch Programming Guide (32650-90014)
Command Definitions
4-461
LOCKGLORIN
NM and CM callable.
Locks a global resource identication number (RIN). Multiple RIN (MR) capability is required
to lock more than one global RIN simultaneously.
Syntax
I16V
U16
CA
LOCKGLORIN( rinnum,lockag,rinpassword);
Parameters
rinnum
16-bit signed integer by value (required)
lockag
Passes the RIN of the resource to be locked. This is the RIN furnished in the
GETRIN command.
16-bit unsigned integer by reference (required)
Passes and returns conditional or unconditional RIN locking specication
through bit (15:1):
Value
0
1
rinpassword
Meaning
Locking takes place only if the RIN is currently unlocked. If
the RIN is not unlocked, control returns to the calling process
immediately with the condition code CCG (0).
Locking takes place unconditionally. If the RIN is currently
locked, the calling process suspends until the RIN becomes
unlocked.
All other bits are ignored. See the discussion of condition codes for the values
returned in lockag.
character array (required)
Passes the RIN password assigned through the GETRIN command. This array
must be a minimum of 10 bytes in length and must be terminated by a
nonalphanumeric ASCII character; a blank is recommended.
Condition Codes
The following condition codes are possible if lockag bit (15:1)=1:
CCE (2)
Request granted. If the calling process has already locked the RIN, lockag
bit (15:1) is set to 0. If the RIN is free, lockag bit (15:1) is set to 1.
CCG (0)
Not returned.
CCL (1)
Request denied. Invalid RIN was specied. Either rinnum is not a global
RIN, or the value is out of bounds for the RIN table.
4-462
Command Definitions
LOCKGLORIN
The following condition codes are possible if lockag bit (15:1)=0:
CCE (2)
Request granted. If the calling process has already locked the RIN, lockag
bit (15:1) is set to 0. If the RIN is free, lockag bit (15:1) is set to 1.
CCG (0)
Request denied. The RIN was locked by another job.
CCL (1)
Request denied because of invalid RIN. Either rinnum is not a global RIN,
or the value is out of bounds for the RIN table.
Operation Notes
The LOCKGLORIN intrinsic can lock any global RIN assigned to a group of users, one process at
a time. When this is done, any other processes that attempt to lock this RIN are suspended.
To use the LOCKGLORIN intrinsic, the RIN number and the RIN password must be known.
Multiple RIN (MR) capability is required to lock two or more global RINs simultaneously. If
you do not have MR capability and attempt to lock two or more RINs simultaneously, the
LOCKGLORIN intrinsic aborts the calling process and prints the following error message:
ONLY ONE RIN CAN BE LOCKED
Lock global RINs using the LOCKGLORIN and FLOCK intrinsics.
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024) and MPE/iX
Commands Reference Manual Volumes 1 and 2 (32650-90003 and
32650-90364)
Command Definitions
4-463
LOCKLOCRIN
NM and CM callable.
Locks a local resource identication number (RIN).
Syntax
I16V
U16
LOCKLOCRIN( rinnum,lockag);
Parameters
rinnum
16-bit signed integer by value (required)
lockag
A previously allocated local RIN; valid values range from 1 to the value
specied in the rincount parameter of the GETLOCRIN intrinsic.
16-bit unsigned integer by reference (required)
Passes and returns conditional or unconditional RIN locking specication
through bit (15:1).
Value
0
1
Meaning
Locking takes place only if the RIN is currently unlocked. If it
is not, control returns to the calling process immediately with
the condition code CCG (0).
Locking takes place unconditionally. If the RIN is currently
locked, the calling process suspends until the RIN becomes
unlocked.
All other bits are ignored. See the discussion of condition codes for the values
returned in lockag.
Operation Notes
Any local RIN assigned to a job can be locked, one process at a time, by using the
LOCKLOCRIN intrinsic. When this is done, other processes within the job that attempt to lock
that RIN are suspended until the locked RIN is released.
4-464
Command Definitions
LOCKLOCRIN
Condition Codes
The following condition codes are possible if lockag bit (15:1)=1:
CCE (2)
Request granted. If the calling process has already locked the RIN, lockag
bit (15:1) is set to 1. If the RIN is free, lockag bit (15:1) is set to 0.
CCG (0)
Not returned.
CCL (1)
Request denied. The RIN is invalid; the rinnum was too large, no local RIN
was allocated, or rinnum specied a number less than or equal to zero.
The following condition codes are possible if lockag bit (15:1)=0:
CCE (2)
Request granted. If the calling process has already locked the RIN, lockag
bit (15:1) is set to 1. If the RIN is free, lockag bit (15:1) is set to 0.
CCG (0)
Request denied. The RIN was locked by another process.
CCL (1)
Request denied. The RIN is invalid; the rinnum was too large, no local RIN
was allocated, or rinnum specied a number less than or equal to zero.
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024).
Command Definitions
4-465
LOCRINOWNER
NM and CM callable.
Determines process identication number (PIN) of the process that locked a local resource
identication number (RIN).
Syntax
I16
I16V
pin:=LOCRINOWNER(rinnum);
Functional Return
pin
16-bit signed integer (assigned functional return)
If the RIN is locked by the parent of the calling process, LOCRINOWNER returns
0. If the RIN is locked by any other process in your process structure,
LOCRINOWNER returns the PIN of that process.
Parameters
rinnum
16-bit signed integer by value (required)
Passes the number of the local RIN for which the PIN of the locking process
is to be determined. The range of valid values is from 1 to the value specied
in the rincount parameter of the GETLOCRIN intrinsic.
Operation Notes
The LOCRINOWNER intrinsic determines the PIN of the process that has a particular local RIN
locked. After a process has acquired local RINs, other processes in the process structure can
lock and unlock these RINs.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-466
Request granted.
Request denied. The local RIN specied by rinnum is not currently locked
by any process.
Request denied. The rinnum parameter was invalid (that is, rinnum was
less than or equal to 0, greater than the RIN table size, or greater than the
number of local RINs currently allocated to this process structure).
Command Definitions
LOCRINOWNER
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024).
Command Definitions
4-467
LOGINFO
NM and CM callable.
Provides information about an opened user logging le (whole le set). User logging (LG) or
system supervisor (OP) capability is required.
Syntax
I32V I16
I16V *
LOGINFO (index,logstatus [,itemnum,item] [...];
You can specify up to four itemnum/item pairs.
Note
Parameters
index
32-bit signed integer by value (required)
logstatus
Passes your access to the user logging system. This is the value returned in
the index parameter of the OPENLOG intrinsic.
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the
intrinsic call:
Value
0
2
4
7
14
17
18
Meaning
Successful
Parameter out of bounds
Incorrect index parameter
Illegal capability; user logging (LG) or system supervisor (OP)
capability required
Invalid access
Either itemnum or item missing
Invalid itemnum
itemnum
16-bit signed integer by value (optional)
item
Species which item value is to be returned. (Refer to Table 4-23
array whose type varies (optional)
Returns the value of the item specied by the corresponding itemnum . Refer
to Table 4-23.
4-468
Command Definitions
LOGINFO
Table 4-23. LOGINFO Itemnum/Item Values
Itemnum Mnemonic
Item Description
1
I32
Total number of records written in current le
2
I32
Current le size
3
I32
Current le space left
4
I16
Number of users
5
I32
Total records written in whole le set
6
CA
Current log le name
7
I16
Current log le type:
0
1
DISK
TAPE
8
CA
Previous log le name
9
I16
Previous log le type:
0
1
DISK
TAPE
10
U16
CHANGELOG allowed (true/false)
11
U16
AUTO allowed (true/false)
12
I16
Current le sequence number
13
I16
Log status:
0
1
2
3
INACTIVE
ACTIVE
Close pending
Stop pending
Related Information
Intrinsics
Commands
Manuals
None
SHOWLOGSTATUS
User Logging Programmer's Guide (32650-90027)
Command Definitions
4-469
LOGSTATUS
NM and CM callable.
Provides information about a currently opened user logging le. User logging (LG) or system
supervisor (OP) capability is required.
Syntax
I32 U16A I16
LOGSTATUS(index,loginfo,logstatus);
Parameters
index
32-bit signed integer by reference (required)
loginfo
Passes your access to the user logging system. This is the value returned in
the index parameter of the OPENLOG intrinsic.
16-bit unsigned integer array (required)
logstatus
Returns the following information:
The total records written in current logging le (a 32-bit value in elements 0
and 1 of loginfo).
The size, in records, of the current logging le (a 32-bit value in elements 2
and 3 of loginfo).
The space, in records, remaining in the current logging le (a 32-bit value in
elements 4 and 5 of loginfo).
The number of users using the logging le (a 16-bit value in element 6 of
loginfo).
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the
intrinsic call:
Value
0
2
4
7
14
4-470
Command Definitions
Meaning
Successful
Parameter out of bounds
Incorrect index parameter
Illegal capability; user logging (LG) or system supervisor (OP)
capability required
Invalid access
LOGSTATUS
Related Information
Intrinsics
Commands
Manuals
None
SHOWLOGSTATUS
User Logging Programmer's Guide (32650-90027)
Command Definitions
4-471
MAIL
NM and CM callable.
Determines the status of the mailbox used by its parent or child. Process handling (PH)
capability is required.
Syntax
U16
I16V I16
mailstatus:=MAIL(pin,length);
Functional Return
mailstatus
16-bit unsigned integer (assigned functional return)
Returns the status of the mailbox:
Value
0
1
2
3
4
Meaning
Mailbox empty.
Contains previous outgoing mail from this calling process that
the destination process has not yet collected.
Contains incoming mail awaiting collection by this calling
process. The length of the mail is returned in length .
An error occurred, an invalid pin was specied, or a bounds
check failed.
Temporarily inaccessible, other intrinsics are using it in the
preparation or analysis of mail.
Parameters
pin
length
16-bit signed integer by value (required)
Passes the mailbox to be tested. If pin species the mailbox of a child
process, it must be the process identication number (PIN) of that child. Zero
species the mailbox of a parent process.
16 bit signed integer by reference (required)
Returns the length, in half words, of any incoming mail in the mailbox.
4-472
Command Definitions
MAIL
Operation Notes
If the mailbox contains mail that is awaiting collection by this process, the length of this
message (in half words) is returned to the calling process in the length parameter. This
enables the calling process to initialize its stack in preparation for receipt of the message.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The mailbox mailstatus was tested.
Request denied. An illegal pin parameter was specied. The value of 3 is
returned to the calling process through mailstatus .
Request denied. The length parameter denes stack address that does not
have write access.
Related Information
Intrinsics
Commands
Manuals
None
None
Interprocess Communication Programmer's Guide (32650-90019)
Command Definitions
4-473
MERGEEND
NM and CM callable.
Restores the data stack to its original state and ends the merging operation.
Syntax
MERGEEND;
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the MERGE program.
Not returned.
Request denied. An error occurred during the MERGE program.
Operation Notes
Call this intrinsic only if the MERGEINIT intrinsic was called.
Related Information
Intrinsics
Commands
Manuals
4-474
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
MERGEERRORMESS
MERGEERRORMESS
NM and CM callable.
Retrieves a message if a fatal error occurs during the MERGE/XL operation and converts
MERGEINIT error code values into ASCII strings.
Syntax
I16V
CA
I16
MERGEERRORMESS(errorcode,message,length);
Parameters
errorcode
16-bit signed integer by value
message
Returns the error number from the MERGEINIT errorparm parameter.
character array
length
Returns the text of the error message. This parameter must be at least 80
characters long.
16-bit signed integer
Returns the length of the message parameter.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-475
MERGEINIT
NM and CM callable.
Initializes the MERGE/XL subsystem and the merging of two or more sorted les.
Syntax
I16A
PROC
I16A
MERGEINIT(inputles,preprocessor,outputles,
PROC
I16V I16V I16A
postprocessor,keysonly,numkeys,keys,
I16A
PROC
PROC
I16A
I16
altseq,keycompare,errorproc,statistics,failure,
I16
I16
I16A
errorparm,spaceallocation,charseq);
Parameters
inputles
16-bit signed integer array (optional)
preprocessor
Passes the le identication numbers of the input les to be merged. The last
element of this array should be set to zero. If the les are opened with either
the NOBUF or MR (multirecord) access option (aoption ), the MERGE program
performs the buering and blocking/deblocking. $NULL is not a valid input
le.
procedure (optional)
outputles
Do not specify, maintain parameter position.
16-bit signed integer array (optional)
postprocessor
Passes the le identication number of the output le. The second array
element must be a zero, indicating the end of the array. If the les are opened
with either the NOBUF or MR (multi-record) access option (aoption ), the
MERGE program performs the buering and blocking/deblocking.
procedure (optional)
length
Do not specify, maintain parameter position.
16-bit signed integer
Denotes the number of characters in the record.
4-476
Command Definitions
MERGEINIT
keysonly
16-bit signed integer by value (optional)
Passes a ag that determines if only keys are sent as output. If true, the
key elds are concatenated together with the major key on the left and the
remaining keys following. If false, the entire record is sent as output.
numkeys
Default: false.
16-bit signed integer (optional)
keys
Passes the number of keys used during the comparison of records. This
parameter can be either equal to or greater than one. If you specify the
numkeys parameter, you must also specify the keys parameter. Together,
numkeys and keys describe the way records are merged.
16-bit signed integer array (optional)
Passes information about the keys used during comparison of records. If
you specify the keys parameter, you must specify the numkeys parameter.
Together, keys and numkeys describe the way records are merged.
The rst element gives the position of the rst character of the key within
the record. The second element gives the number of characters in the key.
Bits (0:8) of the third element give the ordering sequence of the records (0 for
ascending, 1 for descending). Bits (8:8) of the third element indicate the type
of data according to the following convention:
Value
0
1
2
3
4
5
6
Meaning
8-Bit unsigned integer
Twos complement (including 16-bit and 32-bit signed integer)
Floating-point (including real and long)
Packed decimal
Display trailing sign
Packed decimal with even number of digits
Display leading sign
Command Definitions
4-477
MERGEINIT
Value
7
8
9
11
12
Meaning
Display leading sign separate
Display trailing sign separate
Character (using the collating sequence of charseq )
Short oating-point decimal
Floating-point decimal
Note
The integrity of the keys array must be maintained throughout the MERGE
operation. Do not change it until after you have called the MERGEEND intrinsic.
altseq
16-bit signed integer array (optional)
Passes an alternate collating sequence. Bits (0:8) of the rst element are
specied according to the following table, where the sequence comprises the
columns and the data comprises the rows:
ASCII
ASCII
chr(255)
EBCDIC char(1)
EBCDIC ALTSEQ
chr(2)
chr(0)
chr(255) undened
Bits (8:8) of the rst element specify one fewer than the total number of
characters in the collating sequence (in this instance, chr(255) or %377).
keycompare
The remaining array elements comprise the actual collating sequence
responsible for the particular MERGE operation.
procedure (reserved)
errorproc
Do not specify this parameter, but maintain parameter position.
procedure (reserved)
Do not specify this parameter, but maintain parameter position.
4-478
Command Definitions
MERGEINIT
statistics
16-bit signed integer array (optional)
Returns information on the MERGE operation, as follows:
Value
1
2,3
4
5,6
7,8
9,10
Meaning
Number of input les
Number of merged records (32-bit integer)
Space available for merging
Number of comparisons (32-bit integer)
CPU time in milliseconds (32-bit integer)
Elapsed time in milliseconds (32-bit integer)
failure
16-bit signed integer (optional)
errorparm
Returns a true value (-1) if a fatal error occurs; otherwise failure returns a
false value (0). Refer also to the discussion of condition codes.
16-bit signed integer (optional)
Returns the error number if an error occurs. Use the MERGEERRORMESS
intrinsic to obtain the error message text.
spaceallocation 16-bit signed integer (reserved)
charseq
Do not specify this parameter, but maintain parameter position.
16-bit signed integer array (optional)
Passes language information in a two-element array. Set the rst element to
1. Set the second element to the language ID number of the native language
whose collating sequence is to be used to sort keys of type 9 (character).
Command Definitions
4-479
MERGEINIT
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the MERGE program. The value
of the failure parameter of the MERGEINIT intrinsic is set to false.
Not returned.
Request denied. An error occurred during the MERGE program. The value of
the failure parameter of the MERGEINIT intrinsic is set to true.
Related Information
Intrinsics
Commands
Manuals
4-480
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
MERGEOUTPUT
MERGEOUTPUT
NM and CM callable.
Provides an alternative method of specifying how records are output from the MERGE
program.
Syntax
CA I16
MERGEOUTPUT(record,length);
Parameters
record
16-bit character array
length
Returns the next output record.
16-bit signed integer
Returns the length of the record parameter value.
Operation Notes
MERGEOUTPUT requests records from MERGEINIT, one at a time, if the outputles parameter in
the call to the MERGEINIT intrinsic was not specied. Call MERGEOUTPUT from the program
after a call to MERGEINIT, but before a call to MERGEEND.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-481
MERGESTAT
NM and CM callable.
Prints the MERGE program statistics on $STDLIST.
Syntax
I16A
MERGESTAT(statistics);
Parameters
statistics
16-bit signed integer array
Returns MERGE program statistics, such as the number of input les, the
number of records, the space available, the number of compares, the CPU
time in minutes, and the elapsed time in minutes.
Operation Notes
Call MERGESTAT after you have called the MERGEEND intrinsic.
Related Information
Intrinsics
Commands
Manuals
4-482
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
MERGETITLE
MERGETITLE
NM and CM callable.
Prints the version number and title of the merge segment on $STDLIST and prints the date
and time produced by the DATELINE intrinsic.
Syntax
MERGETITLE;
Operation Notes
MERGETITLE can be called from a program any time after the system intrinsics have been
declared.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080).
Command Definitions
4-483
MYCOMMAND
NM and CM callable (dierence noted below).
Parses (delineates and denes) parameters for a user-dened command image.
Syntax
I16
CA
CA
entrynum:=MYCOMMAND(cmdimage,delimiters,
I16V
I16
CA
@*
I32A
maxparms,numparms,params,
dictionar,denition);
Functional Return
entrynum
16-bit signed integer (assigned functional return)
Returns the command entry number. If the dictionary parameter is not
specied, 0 is returned.
Parameters
cmdimage
character array (required)
delimiters
Passes one of two things:
Command name (if the dictionary parameter is specied), then parameters
and a carriage-return character (%15). The command name is delimited by
the rst nonalphanumeric character and cannot be preceded by any leading
blanks. One or more blanks is expected after the command name, preceding
the parameter list. The parameters are formatted and referenced in the
params array and cmdimage is converted to uppercase, and the character
array specied by dictionary is searched for a name matching the command.
Command parameters (if the dictionary parameter is not specied), then a
carriage-return character (%15). These parameters are formatted. Leading
and trailing blanks are ignored. Lowercase is upshifted.
character array (optional)
A cmdimage must begin with an alphabetic character. The rst
non-alphanumeric character (or space) encountered terminates the command
name. Whatever follows is interpreted as an element of the parameter list.
Passes a string of up to 32 legal delimiters, each of which is an ASCII special
character. The last character must be a carriage return. Each delimiter is
identied later by its position in this string.
maxparms
4-484
Default: The delimiter array \,=; (carriage return)".
16-bit signed integer by value (required)
Command Definitions
MYCOMMAND
numparms
params
Passes the maximum number of parameters expected in cmdimage. Accepts
values from 0 to 8192.
16-bit signed integer by reference (required)
Returns the number of parameters found in cmdimage.
32-bit signed integer array (required)
Returns an array of maxparms entries. Numparms entries are returned
that delineate the parameters. Each entry consists of two 32-bit words. When
the intrinsic is executed, the rst numparms entries are returned to your
process in this array, with the rst entry corresponding to the rst parameter,
the second entry corresponding to the second parameter, and so forth. The
parameter elds of cmdimage are delimited by the delimiters specied in
delimiters . The pointer in the rst word of each entry points to the parameter
in cmdimage. The string in cmdimage is upshifted. The second word of
params contains the delimiter number and parameter information. Each
word in the array named by params contains the following information:
Word 1: The pointer to the rst character of the parameter. If the
parameter is empty or all blanks, the pointer indicates the location of the
delimiter.
Word 2: Bits that describe the parameter:
Bits
27:5
26:1
Value/Meaning
The zero-relative position of the delimiter in delimiters . For
example, if you use the default delimiters array and the current
parameter is delimited by a semicolon, this eld contains 2.
Special characters indicator bit (set by MYCOMMAND):
0
1
The parameter contains no special characters.
The parameter contains special characters other than
those listed in delimiters .
Command Definitions
4-485
MYCOMMAND
Bits
Value/Meaning
25:1
Numeric character indicator:
24:1
0
The parameter does not contain numeric characters.
1
The parameter contains numeric characters.
Alphabetic characters indicator:
16:8
0:16
dictionary
0
The parameter does not contain alphabetic characters.
1
The parameter contains alphabetic characters.
The length of the parameter in bytes. This value is zero if you
omit the parameter.
Always zero.
character array (optional)
Passes the character array that is to be searched for the command name in
cmdimage. The format must be identical to that of the dictionary parameter
in the SEARCH intrinsic. The command, delimited by a blank, is extracted
from cmdimage, and the SEARCH intrinsic is called with the command name
used as the buer parameter of SEARCH. If the command name is found in
dictionary , the functional return is its entry number. If the command is not
found, or if the dictionary parameter is not specied, the functional return
is zero. If dictionary is specied, but the command name is not found in
dictionary , the parameters specied in cmdimage are not formatted.
denition
If this parameter is omitted, the functional return is 0.
(NM) 32-bit address (optional)
(CM) 16-bit address (optional)
Returns a pointer to the byte following the command in dictionary . This
should be the denition , but may be invalid if denition is not used for a
command. Check the return status before the pointer is used.
4-486
Command Definitions
MYCOMMAND
Operation Notes
The MYCOMMAND intrinsic analyzes the command string, identifying the location and
characteristics of each parameter. If the dictionary is specied, the rst parameter is
considered a command name. The array specied in dictionary is searched for the command
name. This dictionary is specially formatted as a SEARCH intrinsic array. (Refer to the
SEARCH intrinsic for the format of the array.) The entry number for the match is returned in
entrynum . If a denition exists for the matching entry, its address is returned in denition .
All remaining entries in the command string are analyzed as parameters. (If dictionary is not
entered, all input is considered parameter data.) A parameter consists of all characters from
the current pointer position to the next delimiter. A pointer to rst character is determined.
Valid delimiters are dened in delimiters or by the default delimiter \,=;(carriage return)".
The delimiter type is identied by its position in the dened delimiter list, for example, a
comma is identied as 1, and a semicolon as 3. The contents of the parameter are identied as
special characters, numeric, or alphanumeric characters.
Results of the analysis are returned in the array params . Two words of information are
specied for each parameter. The location pointer is entered in word 1, and the delimiter and
character information are entered in word 2 for each parameter. A maximum of maxparms
parameters are analyzed. The actual number of parameters found are returned to numparms .
The params array can then be referred to in subsequent commands to access the parameter
data.
If the number of characters in cmdimage exceeds 255 characters and no delimiter is present,
the calling process is aborted and the following error message is printed:
PARSED PARAM OF COMIMAGE > 255 CHARACTERS
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The parameters were formatted, without exception. If
dictionary was specied, the functional return is the command entry number.
Request granted. More parameters were found in cmdimage than were
allowed by maxparms. Only the rst maxparms of these parameters were
formatted in params and returned.
Request denied. The dictionary parameter was specied, but the command
name was not located in the array dictionary . The parameters in cmdimage
were not formatted.
Related Information
Intrinsics
Commands
Manuals
SEARCH
None
None
Command Definitions
4-487
NLAPPEND
NM and CM callable.
Appends a language ID number to a le name that allows an application to designate which
language-dependent le to use.
Syntax
CA
I16V U16A
NLAPPEND(formaldesig,langnum,error);
Parameters
formaldesig
character array (required)
langnum
Passes and returns a formal le designator. When passed, the le name must
end with three blanks. When returned, the language ID has been appended to
the name.
16-bit signed integer by value (required)
error
Contains the language ID number, specifying the catalog to be opened.
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid le name
File name not terminated by three blanks
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
Commands
Manuals
4-488
CATCLOSE, CATOPEN, CATREAD
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLCOLLATE
NLCOLLATE
NM and CM callable.
Collates two character strings according to the specied language collating sequence and
determines a lexical ordering.
Syntax
CA
CA
I16V
I16
NLCOLLATE(buer1,buer2,buerlength,result,
I16V
U16A U16A
langnum,error,collseq);
Parameters
buer1
character array (required)
buer2
Passes the rst character string to be collated.
character array (required)
buerlength
Passes the second character string to be collated.
16-bit signed integer by value (required)
result
Passes the length (in bytes) of buer1 and buer2.
16-bit signed integer by reference (required)
Returns the result of the collated character strings (buer1 and buer2):
Value
0
-1
1
langnum
Meaning
buer1 collates equal to buer2
buer1 collates before buer2
buer1 collates after buer2
The result is 0 if a nonzero error is returned.
16-bit signed integer by value (required)
Contains the language ID number, specifying the collating sequence to be
used.
Command Definitions
4-489
NLCOLLATE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid collating table entry
Invalid buerlength parameter
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
collseq
16-bit unsigned integer array (optional)
Passes the native language collating sequence table as returned by
itemnum =11 of the NLINFO intrinsic. If this parameter is present, langnum is
ignored, and this routine is more ecient. Refer to itemnum s 11 and 27 of the
NLINFO intrinsic.
Related Information
Intrinsics
NLFINDSTR, NLJUDGE, NLKEYCOMPARE, NLREPCHAR, NLSCANMOVE,
NLSWITCHBUF, NLTRANSLATE
Commands
Manuals
None
4-490
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLCOLLATE2
NLCOLLATE2
NM callable.
Collates two character strings according to the specied language collating sequence and
determines a lexical ordering. Designed to be used with a COBOL program.
Syntax
I32
CA
I32V CA
I32V
result:=NLCOLLATE2(buer1,len1,buer2,len2,
I16V
U16A U16A U16A
langnum,error,collseq);
Parameters
result
32-bit signed integer by reference (required)
Returns the result of the collated character strings (buer1 and buer2):
Value
0
-1
1
Meaning
buer1 collates equal to buer2
buer1 collates before buer2
buer1 collates after buer2
buer1
The result is 0 if a nonzero error is returned.
character array (required)
len1
Passes the rst character string to be collated.
32-bit signed integer by value (required)
buer2
The length, in bytes, of the rst character string.
character array (required)
len2
Passes the second character string to be collated.
32-bit signed integer by value (required)
langnum
The length, in bytes, of the second character string.
16-bit signed integer by value (required)
Contains the language ID number, specifying the collating sequence to be
used.
Command Definitions
4-491
NLCOLLATE2
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid collating table entry
Invalid buerlength parameter
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
collseq
16-bit unsigned integer array (optional)
Passes the native language collating sequence table as returned by
itemnum =11 of the NLINFO intrinsic. If this parameter is present, langnum is
ignored, and this routine is more ecient. Refer to itemnum s 11 and 27 of the
NLINFO intrinsic.
Related Information
Intrinsics
NLFINDSTR, NLJUDGE, NLKEYCOMPARE, NLREPCHAR, NLSCANMOVE,
NLSWITCHBUF, NLTRANSLATE
Commands
Manuals
None
4-492
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLCONVCLOCK
NLCONVCLOCK
NM and CM callable.
Converts the time format from a character string to numeric value; checks the input string
using the formatting template returned by itemnum =3 of the NLINFO intrinsic, then converts
the time to the general time format returned by the CLOCK intrinsic.
Syntax
I32
CA
I16V
I16V
time:=NLCONVCLOCK(buer,buerlength,langnum,
U16A
error);
Functional Return
time
32-bit signed integer (assigned functional return)
Returns the time in the following format:
Bits
Value/Meaning
8:8
0:8
Minute of hour
Hour of day
Parameters
buer
character array (required)
buerlength
Passes the formatted time to be converted.
16-bit signed integer by value (required)
langnum
Passes the length of buer (in bytes).
16-bit signed integer by value (required)
Contains the language ID number, specifying the custom time format for
buer.
Command Definitions
4-493
NLCONVCLOCK
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid time string
Invalid length
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
NLCONVCUSTDATE, NLFMTCALENDAR, NLFMTCLOCK, NLFMTCUSTDATE,
NLFMTDATE, NLFMTLONGCAL
Commands
Manuals
None
4-494
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLCONVCUSTDATE
NLCONVCUSTDATE
NM and CM callable.
Converts the custom date format from a character string to a numeric value; checks the input
string by using the formatting template returned by item 2 of the NLINFO intrinsic, then
converts the date to the general date format as returned by the CALENDAR intrinsic.
Syntax
U16
CA
I16V
date:=NLCONVCUSTDATE(buer,buerlength,
I16V
U16A
langnum,error);
Functional Return
date
16-bit unsigned integer (assigned functional return)
Returns the date in the following format:
Bits
Value/Meaning
7:9
0:7
Day of year
Year of century
Parameters
buer
character array(required)
buerlength
Passes the formatted date to be converted into custom date format. Leading
and trailing blanks are ignored.
16-bit signed integer by value (required)
langnum
Contains the length of buer (in bytes).
16-bit signed integer by value (required)
Contains the language ID number, specifying the custom date format for
buer.
Command Definitions
4-495
NLCONVCUSTDATE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid date string
Invalid string length
*NLS internal error
*NLS internal error
Separator character in buer does not match custom date
template
Length of date string > 13 characters (excluding leading and
trailing blanks)
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
When a byte array is passed the code receives the starting position and the
length. There is no way for the code to determine if the length you speciy is
correct. Therefore, an error of 4 (invalid string length) is returned only if the
specied buer length is 0 or a negative number. If the passed array length is
greater than zero, but is still incorrect, unpredictable results can occur.
Note
Related Information
Intrinsics
NLCONVCLOCK, NLFMTCALENDAR, NLFMTCLOCK, NLFMTCUSTDATE, NLFMTDATE,
NLFMTLONGCAL
Commands
Manuals
None
4-496
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLCONVNUM
NLCONVNUM
NM and CM callable.
Converts native language numbers with native decimal and thousands separators to an ASCII
number with NATIVE-3000 decimal and thousands separators. Optionally, the decimal and
thousands separators can be removed.
Syntax
I16V
CA
I16V
CA
NLCONVNUM(langnum,instring,inlength,outstring,
I16V U16V U16V
outlength,error,numspec,
U16V U16V
O-V
fmtmask,decimals);
Parameters
langnum
16-bit signed integer by value (required)
instring
Contains the language ID number, specifying which numeric formatting rules
are to be used in the conversion.
character array (required)
inlength
Contains the native language formatted number to be converted. Leading and
trailing spaces are ignored.
16-bit signed integer by value (required)
outstring
outlength
Passes the length, in bytes, of instring.
character array (required)
Contains the converted output, left justied in the buer.Outstring can
reference the same address as instring.
16-bit signed integer by value (required)
Passes the length, in bytes, of outstring. If the call is successful, outlength
contains the actual length of the converted number.
Command Definitions
4-497
NLCONVNUM
error
16-bit unsigned integer by value (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
9
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid length specied (inlength or outlength )
Invalid number specied (instring )
*NLS internal error
*NLS internal error
Truncation occurred (outstring partially formatted)
Invalid numspec parameter
Invalid fmtmask parameter
* Do not apply to calls with langnum equal to 0 (NATIVE3000/XL).
numspec
16-bit unsigned integer by value (optional)
Returns a byte array from NLNUMSPEC, containing format information. If this
parameter is present, langnum is ignored and performance is improved (refer
to NLNUMSPEC).
4-498
Command Definitions
NLCONVNUM
fmtmask
16-bit unsigned integer by value (optional)
Species how to format the number. The default value is 0 and indicates
substitution only.
Bits
15:1
14:1
13:1
0:13
decimals
Value/Meaning
0
Convert thousands separators
1
Strip thousands separators
0
Convert decimal separators
1
Strip decimal separators
0
Any character can be in instring (no validation as a
number is performed)
1
Number contained in instring (no validation as a number
is performed)
Reserved for the operating system
16-bit unsigned integer by value (optional)
If fmtmask bit 13 is set to 1, decimals returns the number of decimal places in
the input number.
Operation Notes
Split-stack calls are not permitted.
This intrinsic either:
Converts a native language formatted number to an ASCII number with the NATIVE-3000
decimal separator (.) and thousands separator (,) for use in further conversion to
INTEGER, REAL, and so on.
Converts the decimal and thousands separators, or strips them (see fmtmask ), to the
NATIVE-3000 equivalent.
For languages using an alternate set of digits (ARABIC and HINDI digits only), this intrinsic
converts the digits to ASCII for recognition and use as numeric characters.
Related Information
Intrinsics
Commands
Manuals
NLFMTNUM, NLNUMSPEC, NLSUBSTR
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-499
NLFINDSTR
NM and CM callable.
Searches string1 for string2, and returns an integer value indicating the oset in string1
where string2 was found.
Syntax
I16
I16V
CA
I16V
CA
oset:=NLFINDSTR(langnum,string1,length1,string2,
I16V
U16A
U16A
length2,error,charset);
Functional Return
oset
16-bit signed integer (assigned functional return)
Returns a -1 if string2 is not found in string1.
Parameters
langnum
16-bit signed integer by value (required)
string1
Contains the language ID number.
character array (required)
length1
Contains the string of characters to be searched. It can contain 1 byte and 2
byte Asian characters.
16-bit signed integer by value (required)
string2
Passes the length, in bytes, of string1.
character array (required)
length2
Contains the character string to be searched for.
16-bit signed integer by value (required)
4-500
Passes the length, in bytes, of string2.
Command Definitions
NLFINDSTR
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
charset
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid length1 parameter
Invalid length2 parameter
*NLS internal error
*NLS internal error
* Do not apply to calls with langnum equal to 0 (NATIVE3000/XL).
16-bit unsigned integer array (optional)
Contains the character set denition for the language to be used, as returned
by itemnum = 12 of the NLINFO intrinsic. When specifying a character set, be
sure that the language ID used matches the character set.
Operation Notes
Split-stack calls are not permitted.
Related Information
Intrinsics
NLCOLLATE, NLJUDGE, NLKEYCOMPARE, NLREPCHAR, NLSCANMOVE,
NLSWITCHBUF, NLTRANSLATE
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-501
NLFMTCALENDAR
NM and CM callable.
Formats the date according to language-dependent templates. The formatting is done
according to the template returned by itemnum = 1 of the NLINFO intrinsic.
Syntax
U16V CA
I16V U16A
NLFMTCALENDAR(date,buer,langnum,error);
Parameters
date
16-bit unsigned integer by value (required)
Contains the date format returned by the CALENDAR intrinsic:
Bits
7:9
0:7
Value/Meaning
Day of year
Year of century
buer
character array (required)
langnum
Returns the formatted date. This string is 18 characters long and is padded
with blanks (if necessary). Using a buer of a dierent size may produce
unexpected results.
16-bit signed integer by value (required)
Contains the language ID number, specifying the calendar template to be
used. A langnum of 0 returns the date formatted as if FMTCALENDAR were
used (for example, FRI, OCT 1, 1982).
4-502
Command Definitions
NLFMTCALENDAR
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid date value
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
NLCONVCLOCK, NLCONVCUSTDATE, NLFMTCLOCK, NLFMTCUSTDATE, NLFMTDATE,
NLFMTLONGCAL
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-503
NLFMTCLOCK
NM and CM callable.
Formats the time of day, in the specied language, obtained with the CLOCK intrinsic.
Syntax
I32V CA
I16V U16A
NLFMTCLOCK( time,buer,langnum,error);
Parameters
time
32-bit signed integer by value (required)
Contains the time format returned by the CLOCK intrinsic:
Bits
24:8
16:8
8:8
0:8
Value/Meaning
Tenths of seconds
Seconds
Minute of hour
Hour of day
buer
character array (required)
langnum
Returns the formatted time of day in an 8-character array. Using a buer of a
dierent size may produce unexpected results.
16-bit signed integer by value (required)
Contains the language ID number, specifying which format to use. A
langnum of 0 returns the time formatted as if you used FMTCLOCK.
4-504
Command Definitions
NLFMTCLOCK
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid time format
*NLS internal error
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
NLCONVCLOCK, NLCONVCUSTDATE, NLFMTCALENDAR, NLFMTCUSTDATE,
NLFMTDATE, NLFMTLONGCAL
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-505
NLFMTCUSTDATE
NM and CM callable.
Formats the general date format returned by the CALENDAR intrinsic into the custom date
format for a native language. A custom date is an abbreviated format such as 10/1/82 or
82.10.1. The formatting is done according to the template returned by itemnum = 2 of the
NLINFO intrinsic.
Syntax
U16V CA
I16V U16A
NLFMTCUSTDATE(date,buer,langnum,error);
Parameters
date
16-bit unsigned integer by value (required)
Contains the date format returned by the CALENDAR intrinsic:
Bits
7:9
0:7
Value/Meaning
Day of year
Year of century
buer
character array (required)
langnum
Returns the formatted date in a 13-character array. Using a buer of a
dierent size may produce unexpected results.
16-bit signed integer by value (required)
Contains the language ID number, specifying the custom date template to
be used for formatting. A langnum of 0 returns the time formatted as if
FMTCLOCK were used.
4-506
Command Definitions
NLFMTCUSTDATE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid date value
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
NLCONVCLOCK, NLCONVCUSTDATE, NLFMTCALENDAR, NLFMTCLOCK, NLFMTDATE,
NLFMTLONGCAL
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-507
NLFMTDATE
NM and CM callable.
Formats the date and time according to language-dependent templates returned by itemnum s
1 and 3 of the NLINFO intrinsic.
Syntax
U16V I32V CA
I16V
U16A
NLFMTDATE(date,time,buer,langnum,error);
Parameters
date
16-bit unsigned integer by value (required)
Contains the date format returned by the CALENDAR intrinsic:
Bits
7:9
0:7
time
Value/Meaning
Day of year
Year of century
32-bit signed integer by value (required)
Contains the time to be formatted, returned by the CLOCK intrinsic:
Bits
Value/Meaning
8:8
0:8
Minutes of hour
Hour of day
buer
character array (required)
langnum
Returns the formatted date and time in a 28 byte array. Using a buer of a
dierent size may produce unexpected results.
16-bit signed integer by value (required)
Contains the language ID number, specifying the formatting templates to use.
A langnum of 0 returns the date/time string as if FMTDATE were used (for
example, MON, FEB 7, 1983 9:00 AM).
4-508
Command Definitions
NLFMTDATE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid date value
Invalid time value
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Related Information
Intrinsics
NLCONVCLOCK, NLCONVCUSTDATE, NLFMTCALENDAR, NLFMTCLOCK,
NLFMTCUSTDATE, NLFMTLONGCAL
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-509
NLFMTLONGCAL
NM and CM callable.
Formats the supplied date according to the long calendar format. The formatting is done
according to the template returned by NLINFO itemnum =30.
Syntax
LV
BA
IV
LA
NLFMTLONGCAL(date,string,langnum,error)
Parameters
date
logical by value (required)
Contains the date format returned by the CALENDAR intrinsic:
Bits
7:9
0:7
Value/Meaning
Day of year
Year of century
string
byte array (required)
langnum
Contains the formatted long calendar date, padded with blanks if necessary.
integer by value (required)
Contains the language ID number, specifying which format to use.
4-510
Command Definitions
NLFMTLONGCAL
error
logical array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid date format
*NLS internal error
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Operation Notes
Split-stack calls are not permitted.
Related Information
Intrinsics
NLCONVCLOCK, NLCONVCUSTDATE, NLFMTCALENDAR, NLFMTCLOCK,
NLFMTCUSTDATE, NLFMTDATE
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-511
NLFMTNUM
NM and CM callable.
Converts a string containing an ASCII number (can include NATIVE-3000 decimal separator
(.), thousands separator (,), and currency symbol/name ($)) to a language-specic format
using the decimal separator, thousands separator, and currency symbol/name dened for the
native language.
Syntax
I16V
CA
I16V
CA
NLFMTNUM(langnum,instring,inlength,outstring,
I16V
U16A U16A
U16V I16V O-V
outlength,error,numspec,fmtmask,decimals)
Parameters
langnum
16-bit signed integer by value (required)
instring
Contains the language ID number, specifying which format to use.
character array (required)
inlength
Contains the NATIVE-3000 formatted ASCII number to be converted (for
example, $123,456.78). Leading and trailing blanks are allowed.
16-bit signed integer by value (required)
outstring
Contains the length, in bytes, of instring.
character array (required)
outlength
Contains the returned language-specic formatted number. The decimal
separator, thousands separator, and currency symbol/name are replaced (if
present), or are inserted (if specied by fmtmask ), according to the language
denition. The outstring can reference the same address as instring.
16-bit signed integer by value (required)
4-512
Contains the length, in bytes, of outstring. After a successful call, if
outstring is returned left-justied (specied by fmtmask ), outlength returns
the actual length, in characters, of the formatted number.
Command Definitions
NLFMTNUM
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
9
10
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid length specied (inlength or outlength )
Invalid number specied (instring )
*NLS internal error
*NLS internal error
Truncation occurred (outstring partially formatted)
Invalid numspec parameter
Invalid fmtmask parameter
Invalid decimals parameter
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
numspec
16-bit unsigned integer array (optional)
Contains format specications, returned from NLNUMSPEC, for the specied
language (currency/name, decimal separator, and so on). If this parameter is
present, langnum is ignored, and performance is improved.
Command Definitions
4-513
NLFMTNUM
fmtmask
16-bit unsigned integer by value (optional)
Contains formatting specications for the input. The default value is 0, a
simple substitution.
Bits
Value/Meaning
15:1
Thousands separators:
14:1
0
Do not insert thousands separators
1
Insert thousands separators
Decimal separators:
13:1
0
Do not insert decimal separators
1
Insert decimal separators
Currency symbol/name:
11:2
0
Do not insert currency symbol/name
1
Insert currency symbol/name
Output justication:
0
1
2
3
0:11
decimals
Do not justify output
Left-justify output
Right-justify output
Left-justify output and return the formatted number
length in outlength
Reserved for the operating system
16-bit signed integer by value (optional)
Species where to insert the decimal separator. The value is ignored if bit 14
of fmtmask is zero or if a decimal separator is present in the number.
4-514
Command Definitions
NLFMTNUM
Operation Notes
Split-stack calls are not permitted.
This intrinsic operates in substitution mode and formatting mode:
Substitution If fmtmask is omitted or has all bits set to zero, the substitution mode
substitutes the native equivalent for "." and ","; for ARABIC, it substitutes
mode
the alternative set of digits for ASCII digits. The input is not validated as a
number and can contain several numbers. No justication takes place, and the
output is left-truncated if outstring is shorter than instring (for example,
1,234.56 becomes ,234.56).
If any bit 10-15 in fmtmask is set to one, the formatting performs the
Formatting
substitution and formats the input according to fmtmask . In this mode, input
mode
is validated as a number, and only ASCII digits and ".", ",", "-", "+",
and "$" are allowed. Only one sign and one "$" are allowed. They must be
the character(s) in instring. Even if insertion (of the separators) is specied
in fmtmask , the thousands and decimal separators are still valid characters in
the input. In this case, they are substituted. If no justication is specied,
the output is right-justied with the same number of trailing spaces as the
input. If the output is truncated, it is left-truncated.
Note
For languages written right-to-left, trailing spaces in the input are preserved as
leading spaces in the output.
Related Information
Intrinsics
Commands
Manuals
NLCONVNUM, NLNUMSPEC
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-515
NLGETLANG
NM and CM callable.
Returns a language ID number that characterizes the current user, data, or system.
Hewlett-Packard subsystems and application programs use NLGETLANG for automatic
conguration.
Syntax
I16
I16V
U16A
langnum:=NLGETLANG(langtype,error);
Functional Return
langnum
16-bit signed integer (assigned functional return)
Returns the language ID number of the current user, data, or system. If an
error occurs, langnum returns a value of 0 (NATIVE3000/XL).
Parameters
langtype
16-bit signed integer by value (required)
Contains the function number indicating which type of language ID number is
returned. The possible values are:
Value
1
2
3
4-516
Command Definitions
Meaning
The user-interface language; species the language used for
communication between the program and user
The data language; determines how the subsystem performs
various language-dependent data manipulation functions (for
example, sorting, upshifting)
The system default language
NLGETLANG
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
Meaning
Successful
NLS not installed
Found language requested, but not congured on system
Invalid langtype value
No language specied
Operation Notes
The NLGETLANG intrinsic locates the language ID numbers requested by langtype 1 and
2 by referring to the Hewlett-Packard dened job control words (JCWs), NLUSERLANG and
NLDATALANG respectively. If the required JCW does not exist or has a value greater than or
equal to FATAL (32768), The error value of 4 is returned.
Related Information
Intrinsics
Commands
Manuals
ALMANAC, NLINFO
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-517
NLINFO
NM and CM callable.
Returns language-dependent information. The type of information that can be obtained
includes:
Calendar format
Date and time format
Currency
Collating
Translation
Character set
Syntax
I16V
*
I16
U16A
NLINFO(itemnum,item,langnum,error);
Parameters
itemnum
16-bit signed integer by value (required)
item
Contains the item to be returned.
type of variable depends on itemnum (required)
langnum
Returns information requested or the language name or number requested.
Table 4-24 lists the dened itemnums, data types (mnemonics), and a
description of the information returned to item.
16-bit signed integer by reference (required)
Contains the language ID number, for the information requested, except for
NLINFO itemnum s 22 and 24. For NLINFO itemnum = 22, the language ID
number is returned in langnum; for NLINFO itemnum = 24, the character set
ID number is returned in langnum.
4-518
Command Definitions
NLINFO
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7-9
10
Meaning
Successful
*NLS not installed
*Specied language not congured
*Specied character set not congured
No national table present
*NLS internal error
*NLS internal error
Reserved for the operating system
Itemnum out of range
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
Command Definitions
4-519
NLINFO
Table 4-24. NLINFO Itemnum/Item Values
Itemnum Mnemonic
1
CA
Item Description
Returns the calendar format in an 18 byte array. The 18 bytes of the string for
this denition are interpreted as the format description for that language. The
following descriptors are valid:
D
1 byte day abbreviation
DD
2 byte day abbreviation
DDD
3 byte day abbreviation
M
1 byte month abbreviation
MM
2 byte month abbreviation
MMM
3 byte month abbreviation
MMMM 4 byte month abbreviation
mm
Numeric month of the year
dd
Numeric day of the month
yy
Numeric year of the century
yyyy
Numeric year
Nyy
National year
NPyy
National year that can include a before-period symbol
E
1-8 of these are replaced by an equal amount of bytes from the
emperor/country name
Valid separators are any special character. For example, a format can be DDD,
MMM DD, yyyy. Using this format in NATIVE3000/XL results in FRI, MAY 25,
1984.
4-520
Command Definitions
NLINFO
Table 4-24. NLINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
2
CA
Item Description
Returns the custom date format in a 13 byte array. The 13 bytes of the string for
this denition are interpreted as the custom date format description. The
following descriptors are valid:
mm
Numeric month of the year
dd
Numeric day of the month
yy
Numeric year of the century
yyyy
Numeric year
Nyy
National year
NPyy
National year that can include a before-period symbol
Valid separators are any special character. For example, a date format can be
yy/mm/dd. This format in NATIVE3000/XL results in 81/03/25.
3
CA
Returns the clock specication in an 8 byte array. This 8 byte string provides the
clock format description (template) HHSXXYYZ, where the elements specify the
following:
HH
Clock hour specication, either `' or `$'
S
Separator; valid separators can be any special or alphabetic character,
or 0 for no separator between hours and minutes
XX
Symbol for AM
YY
Symbol for PM
Z
Suppresses leading zero (of hours) if blank; prints leading zero if 0
In suppression of leading zero, " " (leading zero suppressed) or 0 (leading zero is
printed) are valid. For example, the format "12:AMPM " results in the formatted
clock information 9:06 AM; the leading zero is suppressed. If the clock
specication were changed to "240
0", the formatted clock information for
the same time is: 0906. Note the four blanks used as place holders to ensure the
correct placement of the leading-zero suppression character.
4
CA
Returns the month abbreviation table in a 48 byte array. Each abbreviation is 4
bytes long, using blank padding where necessary to maintain uniform length in
all native language abbreviations. For example, the NATIVE3000/XL
abbreviations contain 3 bytes plus a blank. The rst 4 bytes of the array contain
the abbreviation of January. For example, the month abbreviation table is:
"JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC "
5
CA
Returns the month table in a 144 byte array. Each month's name can be up to 12
bytes long. Unused space in the month name is padded with blanks where
necessary to equal 12 bytes. The table begins with the language-dependent
equivalent in the native language specied for January. For example, the month
name table is:
"JANUARY FEBRUARY MARCH . . . DECEMBER"
6
CA
Returns the day abbreviation table in a 21 byte array. Each abbreviation is 3
bytes long. The table begins with Sunday. For example, the day abbreviation
table is:
"SUNMONTUEWEDTHUFRISAT"
Command Definitions
4-521
NLINFO
Table 4-24. NLINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
7
CA
Returns the table containing the day of the week in an 84 byte array. Each day is
12 bytes long (with blank padding as needed). The table starts with Sunday. For
example, the day name table is:
"SUNDAY MONDAY TUESDAY . . . SATURDAY"
8
CA
Returns the YES/NO responses in a 12 byte array; the rst 6 bytes contain the
(upshifted) YES response; the second 6 bytes contain the (upshifted) NO response.
9
CA
Returns the symbols for decimal separator and thousands indicator in a 2 byte
array. The rst byte contains the decimal separator, the second byte contains the
thousands indicator. The second byte can take a special value of 0. Do not take
this value literally as a thousands separator; it signies the absence of a
thousands separator for the language chosen.
10
CA
Returns the currency signs in a 6 byte array. The rst byte represents the short
currency symbol (if any) used for business formats; the second byte is a ag
indicating whether the currency symbol precedes or succeeds the number and
whether the currency symbol is preceded or succeeded by blanks. The last four
bytes contain the full currency symbol. The layout of the second byte is:
Bits 0:4 0 - Currency
1 - Currency
2 - Currency
3 - Currency
symbol has no blanks preceding or succeeding it.
symbol has a blank preceding it.
symbol has a blank succeeding it.
symbol has blanks preceding and succeeding it.
Bits 4:4 0 - Currency symbol precedes the number.
1 - Currency symbol succeeds the number.
2 - Currency symbol replaces the decimal separator.
11
U16A
Returns the collating sequence table. A call to NLINFO itemnum =27 determines
the length of this array based on the length of the table of the native language
specied.
12
CA
Returns the character set attribute table in a 256-element (256-half word) array.
Each character contains the numeric identication of the character type:
0
Numeric character
1
Alphabetic lowercase character
2
Alphabetic uppercase character
3
Undened graphic character
4
Special character
5
Control code
13
CA
Returns the ASCII-to-EBCDIC translation table in a 256 byte array.
14
CA
Returns the EBCDIC-to-ASCII translation table in a 256 byte array.
15
CA
Returns the upshift table in a 256 byte array.
16
CA
Returns the downshift table in a 256 byte array.
4-522
Command Definitions
NLINFO
Table 4-24. NLINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
Item Description
17
U16A
Returns the language numbers of all congured languages. The rst element of
this array contains the number of congured languages. The second element
contains the language number of the rst congured language. The third element
contains the language number of the second congured language, and so forth.
(The langnum parameter is disregarded.)
18
I16
Returns -1 if the specied language is supported (congured) on the system.
Otherwise, 0 is returned.
19
I16
Returns the character set ID number supporting the specied language.
20
CA
Returns the uppercase name of the character set supporting the specied
language in a 16 byte array. If the name contains fewer than 16 bytes, it is
padded with blanks.
21
CA
Returns the uppercase name of the specied language in a 16 byte array. If the
name contains fewer than 16 bytes, it is padded with blanks.
22
CA
Passes a language name or number (in ASCII digits) terminated by a blank. The
array can be <= 16 bytes. The associated language ID number is returned to
langnum .
23
I16
Returns -1 if the character set specied is supported (congured) on the system.
Otherwise, 0 is returned.
24
CA
Passes a character set name or number (in ASCII digits) terminated by a blank.
The array can be <= 16 bytes. The associated character set ID number is
returned to langnum .
25
CA
Returns the uppercase name of the specied character set in a 16 byte array. The
langnum parameter must contain the ID number of the character set. If the
name contains fewer than 16 bytes, it is padded with blanks.
26
I16
Returns the class number of the specied language.
27
I16
Returns the length (in half words) of the collating sequence table of the specied
language (see itemnum = 11).
28
I16
Returns the length (in half words) of the national-dependent information table.
If no national table exists for the specied language, error =4 is returned.
29
U16A
Returns the national-dependent information table. To determine the size of this
array, you must rst obtain the length with a call to NLINFO itemnum =28.
Command Definitions
4-523
NLINFO
Table 4-24. NLINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
30
CA
Item Description
A 36 byte array where the long calendar format is returned. It can contain
arbitrary text and the following descriptors:
D
1-3 of these are replaced by an equal number of bytes from the day
abbreviation.
W
1-12 of these are replaced by an equal number of bytes from the day of
week.
dd
Numeric day of month.
M
1-4 of these are replaced by an equal number of bytes from the month
abbreviation.
O
1-12 of these are replaced by an equal number of bytes from the month
of year.
mm
Numeric month of year.
yy
Numeric year of century.
Nyy
National year.
NPyy
National year that can include a before-period symbol.
E
1-8 of these are replaced by an equal number of bytes from the
emperor/country name.
A literal character (~) can be used to indicate that one of the above special
characters are taken literally within a format. For example, a format of
WWWWWWWWW, OOOOOOOOO dd, A.~D.yyyy
results in WEDNESDAY, NOVEMBER 21, A.D. 1984.
31
CA
A 16 byte array where the currency name is returned.
32
CA
An 8 byte array containing information about an alternate set of digits (Arabic
only).
4-524
0-1
Alternative digit separator (integer)
0 - No alternative digits dened
1 - Alternative digits dened
2
Alternative digit 0
3
Alternative digit 9
4
\+" used with alternative digits
5
\-" used with alternative digits
6
Decimal separator used with alternative digits
7
Thousands separator used with alternative digits
Command Definitions
NLINFO
Table 4-24. NLINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
33
34
35
36
CA
U16
U16
U16
Item Description
A 4 byte array containing information about the direction of the language.
0-1
Language direction (integer)
0 - Direction is left-to-right
1 - Direction is right-to-left
2
The right-to-left space
3
Undened
A logical value that returns the data ordering of the language.
0
Keyboard order
1
Left-to-right screen order
2
Right-to-left screen order
A logical value that returns the language character size.
0
1 byte characters (8-bits)
1
2 byte characters (16-bits)
A logical value that returns a true (1), if the language requires suppressing the
leading zero or a blank in the date format.
Related Information
Intrinsics
Commands
Manuals
ALMANAC, NLGETLANG
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-525
NLJUDGE
NM and CM callable.
Judges whether a character is a 1 byte or 2 byte Asian character.
Syntax
I16V
I16V
CA
I16V
n2bytes:=NLJUDGE(langnum,instring,stringlength,
CA U16A
U16A
ags,error,charset);
Functional Return
n2bytes
16-bit signed integer (assigned functional return)
Contains the number of 2 byte Asian characters in a 16-bit signed integer
value that can be used to check a string of characters for Asian characters.
Parameters
langnum
16-bit signed integer by value (required)
instring
Contains the language ID number.
character array (required)
stringlength
Contains the string of characters to be judged.
16-bit signed integer by value (required)
ags
Species the number of bytes in instring.
character array (required)
Contains one of the following values (ASCII characters):
Value
0
1
2
3
4-526
Command Definitions
Meaning
1 byte character
First byte of a 2 byte character
Second byte of a 2 byte character
Invalid Asian character
NLJUDGE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
Meaning
Successful
*NLS not installed
*Specied language is not congured
Invalid string length
Not returned
*NLS internal error
*NLS internal error
*Invalid characters found in instring
* Do not apply to calls with langnum equal to 0 (NATIVE-3000).
charset
16-bit unsigned integer array (optional)
Contains the character set denition for the language to be used, as returned
by itemnum =12 of NLINFO.
Related Information
Intrinsics
NLCOLLATE, NLKEYCOMPARE, NLREPCHAR, NLSCANMOVE, NLSWITCHBUF,
NLSTRANSLATE
Commands
Manuals
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-527
NLKEYCOMPARE
NM and CM callable.
Compares two strings of dierent length (for use with KSAM generic key searching).
Syntax
CA
I16V CA I16V
NLKEYCOMPARE(generickey,length1,key,length2,
I16
I16V U16A U16A
result,langnum,error,collseq);
Parameters
generickey
character array (required)
length1
Passes the generic key to be compared to the keys contained in the record
read by FREAD.
16-bit signed integer by value (required)
key
length2
result
Contains the length, in bytes, of generickey, which must be less than
length2.
character array (required)
Passes an entire key to which you want to compare generickey.
16-bit signed integer by value (required)
Contains the length in bytes of key, which must be greater than length1.
16-bit signed integer by reference (required)
Returns the result of the compare:
4-528
Command Definitions
NLKEYCOMPARE
Value
0
1
2
3
Meaning
The retrieved key matches the generic key exactly for a length
of length .
The retrieved key does not match the generic key; it is dierent
only because of priority (for example, uppercase versus
lowercase characters or accent). The FREAD key is still in range;
records can follow whichever key matches the generic key
exactly.
The retrieved key is less than the generic key (its collating
order precedes the key specied). It does not match generickey .
This means the FREAD call found a record that precedes the
range requested. Records that match generickey can follow.
The retrieved key is greater than the generic key (it collates
after the specied key). This means that the FREAD call found
a record whose key follows the specied range. No records
matching generickey follow.
langnum
16-bit signed integer by value (required)
error
Contains the language ID number, specifying the collating sequence to be
used for the compare.
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid collating table entry
Invalid length parameter
*NLS internal error
*NLS internal error
Value of length1 not less than length2
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
collseq
16-bit unsigned integer array (optional)
Passes the collating sequence table as returned by NLINFO item 11. If this
parameter is present, langnum is ignored, and this routine is much more
ecient.
Command Definitions
4-529
NLKEYCOMPARE
Operation Notes
Use NLKEYCOMPARE when reading a KSAM le in key sequential order in combination with
FREAD, and after a FFINDBYKEY call.
The NLKEYCOMPARE intrinsic lets a program determine whether a generic key search found an
exact match (that is, the generic key is exactly equal to the beginning of the key), or whether
the keys are dierent only because of priority (for example, uppercase versus lowercase or
accent). It also lets the program determine whether an exactly matching key could be farther
along the key sequence.
Related Information
Intrinsics
Commands
Manuals
4-530
NLCOLLATE, NLREPCHAR, NLSCANMOVE, NLSWITCHBUF, NLSTRANSLATE
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLMATCH
NLMATCH
Compares a string against a pattern which has previously been compiled with the
NLMATCHINIT intrinsic.
Syntax
I
result
:= NLMATCH(comp
BA
BA
IV
pattern,string,length);
Functional Return
Zero is returned in result if the string matches the compiled comp
match, the mismatch location is returned.
result
pattern.
Integer Error
Meaning
1
2
100+n
NLS is not installed
The specied language is not congured
n is the mismatch location
If there is no
Parameters
comp pattern Byte array (required)
A byte array containing the compiled form of a comp
NLMATCHINIT.
string
length
pattern as returned by
A pattern consists of a series of special characters that indicate the type of
data to be selected. These characters are:
Byte array (required)
The string to be compared against the comp
Integer by value (required)
pattern.
Length, in bytes, of the string to be compared.
Related Information
Intrinsics
Commands
Manuals
NLMATCHINIT
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-531
NLMATCHINIT
Compiles a pattern into a form for use with the NLMATCH intrinsic.
Syntax
I
BA
I
:= NLMATCHINIT( pattern,pattern
IV
BA
I
langid,comp pattern,comp buf size);
result
len,
Functional Return
Zero is returned if the compilation of pattern is successful. Otherwise theresult contains the
error code.
result
Integer Error
001
002
101
102
104
105
203
900
Meaning
NLS is not installed
The specied language is not congured
Missing \]" or \}" operators
Expecting alpha symbols
Incomplete pattern specied
Bad range operation specied
Pattern too big
Internal state machine error
Parameters
pattern
Byte array (required)
A byte array containing the pattern to be compiled. Leading and training
spaces are ignored.
A pattern consists of a series of special characters that indicate the type of
data to be selected. These characters are:
Char
a
u
l
b
d
?
4-532
Selected
Uppercase, lowercase, or 16-bit Asian character
Uppercase alphabetic character
Lowercase alphabetic character
Blank (space)
Digits, as dened in the NLS character attribute table
Any character
Command Definitions
NLMATCHINIT
Other metacharacter indicate choice, grouping, and ranges:
Char
!
,
:
fg
[]
+
*
Operation
Transparency
Choice
Range
Grouping
Optional
Repetition (one or more)
Repetition (zero or more)
Pattern operators are evaluated in the following order, where x and y are any
character for the language:
Char
Example
!
Transparency
!x
:
Range
x:y
Repetition (1/0 or more)
x+ or x*
Concatenation
xy
Choice
x,y
+/*
,
pattern len
langid
comp
Operation
The repetition, concatenation, and choice operators can be used with
patterns. For instance: x,y are any pattern in this case.
Integer (required)
Length, in bytes, of the pattern to be compiled.
Integer by value (required)
The language ID number of the language to be used in compiling the pattern.
pattern Byte array (required)
comp buf
size
A byte array specifying where the compiled pattern is to be constructed.
Integer (required)
The length of the comp
compiledpattern.
pattern, in bytes, available for constructing the
Command Definitions
4-533
NLMATCHINIT
Operation Notes
NLMATCHINIT converts the regular expression in pattern to a reduced, nite state machine
and places it in comp pattern, wherepattern len is the expression's length in bytes,
andcomp buf size is the maximum size of the comp pattern in bytes.
If comp
buf size is 0 (zero), only a syntax check of pattern is performed and no
comp pattern will be generated.
If NLMATCHINIT returns 0 (zero), the compilation of pattern succeeded.
If comp buf size > 0 (zero), the comp pattern contains the compiled pattern and
comp buf size contains its actual size in bytes.
If NLMATCHINIT is not zero, an error occurred and NLMATCHINIT returns the error code in
return. In such cases, pattern len contains the zero-origin index into pattern and tells you
how far the scan has progressed (the scan may have completed). The pattern description and
grammar are the ones used in VPLUS.
Related Information
Intrinsics
Commands
Manuals
4-534
NLMATCH
Data Entry and Forms Management System VPLUS Reference Manual
(32209-90001) and Native Language Programmer's Guide (32650-90022),
Command Definitions
NLNUMSPEC
NLNUMSPEC
NM and CM callable.
Returns the information needed for formatting and converting numbers. It combines several
calls to NLINFO to simplify the use of native language formatting. By calling NLNUMSPEC once,
and passing the obtained information to NLFMTNUM and NLCONVNUM, implicit calls to NLNUMSPEC
from NLFMTNUM and NLCONVNUM are avoided and performance is improved.
Syntax
I16V
U16A U16A
NLNUMSPEC(langnum,string,error);
Parameters
langnum
16-bit signed integer by value (required)
string
Contains the language ID number.
16-bit unsigned integer array (required)
Contains >= 60 bytes, where the following information is returned:
Byte(s) Meaning
00-01
02-03
Language identication number (integer)
Alternate digit indicator (integer)
04-05
0
No alternate digits exist
1
Alternate digits exist
Language direction indicator (integer)
06-07
08
09
10
11
12
13
14
15
0
Language is left-to-right
1
Language is right-to-left
Alternate digit range (0,9)
Decimal separator (ASCII-digits)
Decimal separator (alternate-digits)
Thousands separator (ASCII-digits)
Thousands separator (alternate-digits)
'+' (alternate-digits)
'-' (alternate-digits)
Right-to-left space
Reserved for the operating system
Command Definitions
4-535
NLNUMSPEC
Byte(s) Meaning
error
16-17
Currency place (integer)
18-19
20-37
38-59
0
Currency symbol
1
Currency symbol succeeds the number
2
Currency symbol replaces the decimal separator
3
Currency symbol precedes the sign
Length of currency symbol (integer), includes spaces
Currency symbol, includes spaces
Reserved for the operating system
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid string
*NLS internal error
*NLS internal error
* Do not apply to calls with langnum equal to 0 (NATIVE3000/XL).
Operation Notes
Split-stack calls are not permitted.
The intrinsic combines NLINFO calls with itemnum s 9, 10, 31, 32, and 33. The information is
formatted where needed (for example, any spaces in the currency symbol/name are included).
The currency symbol/name is the shortest nonblank descriptor, as returned from NLINFO
itemnum s 10 and 31.
This intrinsic does not provide any information not obtainable with NLINFO. It is included for
the convenience of the NLS user. For eciency, the user of this intrinsic calls it only once,
saves the result, and calls NLFMTNUM and/or NLCONVNUM multiple times.
Related Information
Intrinsics
Commands
Manuals
4-536
NLCONVNUM, NLFMTNUM
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLREPCHAR
NLREPCHAR
NM and CM callable.
Replaces all nondisplayable control characters in the string with the replacement character.
Nondisplayable characters are those with attribute 3 (undened graphic character) or 5
(control code), as returned by itemnum =12 of the NLINFO intrinsic.
Syntax
CA
CA
I16V
NLREPCHAR(inbuer,outbuer,buerlength,
CV
I16V U16A U16A
replacechar,langnum,error,charset);
Parameters
inbuer
character array (required)
outbuer
Passes the nondisplayable characters to be replaced.
character array (required)
buerlength
Returns the replaced character string.
16-bit signed integer by value (required)
replacechar
Passes the length, in bytes, of inbuer.
character by value (required)
langnum
Contains the replacement character to be used.
16-bit signed integer by value (required)
Contains the language ID number.
Command Definitions
4-537
NLREPCHAR
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid replacement character
Invalid length parameter
*NLS internal error
*NLS internal error
Invalid charset table entry
Overlapping strings, outbuer overwrites inbuer
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
charset
16-bit unsigned integer array (optional)
Passes the character set denition for the language used, as returned in
NLINFO itemnum = 12. If this parameter is present, langnum is ignored, and
this intrinsic is more ecient.
Related Information
Intrinsics
Commands
Manuals
4-538
NLCOLLATE, NLKEYCOMPARE, NLSCANMOVE, NLSWITCHBUF, NLSTRANSLATE
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLSCANMOVE
NLSCANMOVE
NM and CM callable.
Scans and moves character strings according to character attributes. This function is handled
in a language-dependent manner.
Syntax
I16
CA
CA
U16V
numchar:=NLSCANMOVE( inbuer,outbuer,ags,
I16V
I16V
U16A
buerlength,langnum,error,
U16A CA
charset,shiftinfo);
Functional Return
numchar
16-bit signed integer (assigned functional return)
Contains the number of characters acted upon in the scan or move function.
Parameters
inbuer
character array (required)
outbuer
Passes the source string.
character array (required)
Returns the target string.
Note
If outbuer and inbuer are the same string, this intrinsic performs a scan
function. Otherwise, a move function is performed.
Command Definitions
4-539
NLSCANMOVE
ags
16-bit unsigned integer by value (required)
Contains the ag dening the options for calling the intrinsic and denes the
condition for terminating the scan or move function.
Bits
Value/Meaning
14:2
Alphabetic (NLINFO item 12, types 1 and 2):
13:1
12:1
1
Lowercase
2
Uppercase
3
Uppercase/lowercase
Numeric (NLINFO itemnum =12, type 0)
Special; NLINFO itemnum =12, types:
3
4
5
11:1
Undened graphic character
Special character
Control code
WHILE/UNTIL option, if:
9:2
String scanned while the condition (specied by ags
(12:4)) is true
1
String scanned until the condition (specied by ags
(12:4)) is true
Shift:
0:9
1
Upshift
2
Downshift
Reserved for the operating system
0
buerlength
16-bit signed integer by value (required)
langnum
Passes the maximum number of bytes to be acted upon during the indicated
function.
16-bit signed integer by value (required)
Contains the language ID number, specifying both the character set
denitions of character attributes and the language-specic shift.
4-540
Command Definitions
NLSCANMOVE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
9
Meaning
Successful
*NLS not installed
*Specied language not congured
Overlapping strings; outbuer overwrites inbuer
Invalid buerlength parameter
*NLS internal error
*NLS internal error
Reserved portion of ags not 0
Upshift and downshift requested
Invalid table element
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
charset
16-bit unsigned integer array (optional)
shiftinfo
Passes the character set denition for the language used, as returned in
NLINFO itemnum =12. If present, the langnum parameter is ignored, and this
routine is much more ecient.
character array (optional)
Passes shift information for a desired upshift or downshift (for example, as
returned in NLINFO items 15 or 16 ). This parameter is utilized when bits
(9:2) of ags are not equal to 0. If present, the langnum parameter is
ignored, and this routine is much more ecient.
Related Information
Intrinsics
Commands
Manuals
NLCOLLATE, NLKEYCOMPARE, NLREPCHAR, NLSWITCHBUF, NLSTRANSLATE
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-541
NLSUBSTR
NM and CM callable.
Extracts movelength bytes from the instring to the outstring.
Syntax
CA
I16V
CA
I16
NLSUBSTR(instring,inlength,outstring,outlength,
I16V
16V
I16V
startposition,movelength,langnum,
I16V U16A U16A
ags,error,charset);
Parameters
instring
character array (required)
inlength
Contains the string from which the substring is extracted. The string can
contain both 1 byte and 2 byte Asian characters.
16-bit signed integer by value (required)
outstring
outlength
startposition
Contains the length, in bytes, of instring.
character array (required)
Indicates where substring is placed.
16-bit signed integer by reference (required)
Passes the length, in bytes, of outstring. After a successful call, outlength
returns the actual length of the substring moved to outstring.
16-bit signed integer by value (required)
movelength
Contains the oset into instring where the substring starts. A value of zero
is the beginning point.
16-bit signed integer by value (required)
langnum
Passes the length, in bytes, of the substring.
16-bit signed integer by value (required)
Contains the language ID number.
4-542
Command Definitions
NLSUBSTR
ags
16-bit signed integer by value (required)
Contains the ag word, and is used primarily with Asian languages. It is
meaningless with 1 byte languages. It is used when special treatment is
required:
Bits
Value/Meaning
12:4
Used if the rst character of a substring is the second byte of a
2 byte Asian character:
0000 Return an error condition
0001 Start from startposition +1
0010 Start from startposition -1
0011 Start from startposition , but replace character with a
blank in outstring
0100 Start from startposition regardless
8:4
Used if the last character in a substring is the rst byte of a 2
byte Asian character:
0000 Return an error condition
0001 Move until movelength +1
0010 Move until movelength -1
0011 Move until movelength , but replace character with a
blank in outstring
0100 Move until movelength regardless
0:8
Reserved for the operating system
Command Definitions
4-543
NLSUBSTR
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Meaning
Successful
*NLS not installed
*Specied language not congured
Not returned
Not returned
*NLS internal error
*NLS internal error
Invalid inlength
Invalid startposition
Invalid movelength
Reserved portion of ags not zero
Invalid value for ags ( 8:4)
Invalid value for ags (12:4)
*Start position rst byte of an Asian character, or an overow
condition occurred due to ags
*End position second byte of an Asian character, or an
overow condition occurred due to ags
* Do not apply to calls with langnum equal to 0 (NATIVE-3000).
charset
16-bit unsigned integer array (optional)
Contains the character set denition for the language to be used, as returned
by itemnum = 12 of NLINFO. When specifying a character set, be sure that the
language ID used matches the character set.
Operation Notes
Split-stack calls are not permitted.
Related Information
Intrinsics
Commands
Manuals
4-544
NLCOLLATE, NLKEYCOMPARE, NLREPCHAR, NLSWITCHBUF, NLSTRANSLATE
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
NLSWITCHBUF
NLSWITCHBUF
NM and CM callable.
Converts a string of characters from phonetic order to screen order or from screen order to
phonetic order.
Syntax
I16V
CA
CA
NLSWITCHBUF(langnum,instring,outstring,
I16V
U16V
U16A
stringlength,left-to-right,error);
Parameters
langnum
16-bit signed integer by value (required)
instring
Contains the language ID number.
character array (required)
outstring
Contains the string, in phonetic order, to be converted to screen order.
character array (required)
stringlength
Contains the string after conversion. Outstring and instring can reference
the address.
16-bit signed integer by value (required)
left-to-right
Contains the length, in bytes, of the string to be converted.
16-bit unsigned integer by value (required)
Species whether the implied primary mode of the data (if displayed on a
terminal) is left-to-right (true) or right-to-left (false), determining which
language it is and which strings of characters to switch.
Command Definitions
4-545
NLSWITCHBUF
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not installed
Invalid string length
Not returned
*NLS internal error
*NLS internal error
* Do not apply to calls with langnum equal to 0 (NATIVE3000/XL).
Operation Notes
This intrinsic is designed to handle data for languages written from right-to-left (for example,
ARABIC). Screen order is dened right-to-left if the primary mode of the terminal or printer
is from right-to-left, as it is when used principally for entering or displaying data from a
right-to-left language. Otherwise, screen order is dened to be left-to-right.
NLSWITCHBUF can be used by a program to convert a buer phonetic order (the order in which
the characters is typed at the terminal or spoken by a person) to screen order (the order in
which the characters are displayed on a terminal screen or piece of paper). It can also convert
data from screen order to phonetic order.
In general, phonetic order and screen order are not the same if USASCII text is mixed with
text from a right-to-left language. The relationship between phonetic order and screen order is
further complicated by the use of HINDI digits in ARABIC. (HINDI digits play a third role
intermediate between ASCII characters and characters of the right-to-left language.)
This intrinsic is designed for a special purpose. Its primary value lies in its application to
languages that are written from right-to-left and that may intermix left-to-right text (for
example, the use of ENGLISH in ARABIC text).
NLSWITCHBUF can serve the needs of a general program, one not specically designed for
handling right-to-left data. A general program can call NLSWITCHBUF to convert data from
phonetic order to screen order and back to phonetic order. One example is an editor that
needs to track cursor movement on a terminal against a buer of text in memory. If the data
is not a right-to-left language, then this intrinsic returns the same text (unchanged); for all
other languages, phonetic order and screen order are the same.
4-546
Command Definitions
NLSWITCHBUF
Related Information
Intrinsics
Commands
Manuals
NLCOLLATE, NLKEYCOMPARE, NLREPCHAR, NLSTRANSLATE, NLSUBSTR
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-547
NLTRANSLATE
NM and CM callable.
Translates a string of characters from EBCDIC-to-ASCII or ASCII-to-EBCDIC using the
appropriate native language table.
Syntax
I16V
CA
CA
NLTRANSLATE( transcode,inbuer,outbuer,
I16V
I16V
U16A
buerlength,langnum,error,
CA
transtable);
Parameters
transcode
16-bit signed integer by value (required)
Passes the translation direction:
Value
1
2
Meaning
EBCDIC-to-ASCII translation
ASCII-to-EBCDIC translation
inbuer
character array (required)
outbuer
Passes the string to be translated.
character array (required)
buerlength
langnum
Contains the translated string. The parameters inbuer and outbuer can
specify the same array.
16-bit signed integer by value (required)
Passes the number of bytes of inbuer to be translated.
16-bit signed integer by value (required)
Contains the language ID number, specifying which translation tables are to
be used.
4-548
Command Definitions
NLTRANSLATE
error
16-bit unsigned integer array (required)
Returns two elements: the rst element is the error number; the second
element is reserved and always returns 0. The possible error number values
are:
Value
0
1
2
3
4
5
6
Meaning
Successful
*NLS not installed
*Specied language not congured
Invalid transcode specied
Invalid length parameter
*NLS internal error
*NLS internal error
* Do not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
transtable
character array (optional)
Passes a translation table in a 256 byte array. Each byte contains the
translation of the byte whose value is its index. This parameter corresponds
to itemnum s 13 and 14 of the NLINFO intrinsic. If present, the langnum
parameter is ignored, and this routine is more ecient.
Operation Notes
This intrinsic performs the same function as CTRANSLATE, using native language tables.
The inbuer parameter is translated into outbuer for length of buerlength, using a
translation table, and is determined as follows:
1. If transtable is present, a translation is made using transtable .
2. If langnum equals NATIVE3000/XL, a standard ASCII-to-EBCDIC or EBCDIC-to-ASCII
translation is made.
3. The ASCII-to-EBCDIC or EBCDIC-to-ASCII translation table for the language specied is
used.
Related Information
Intrinsics
Commands
Manuals
NLCOLLATE, NLKEYCOMPARE, NLREPCHAR, NLSUBSTR
None
Native Language Programmer's Guide (32650-90022)
Command Definitions
4-549
NLTRANSLATE
OPENLOG
NM and CM callable.
Provides access to the user logging facility. User logging (LG) or system supervisor (OP)
capability is required.
Syntax
I32 CA
CA I16
I16
OPENLOG(index,logid,pass,mode,logstatus);
Parameters
index
32-bit signed integer by reference (required)
logid
Returns the user logging access. The User Logging facility uses the value of
the index parameter to check the validity of subsequent calls to the other
user logging intrinsics. The value returned is valid only for the process that
made the OPENLOG call.
character array (required)
pass
Passes the user logging identier. Contains up to eight alphanumeric
characters. Arrays < 8-characters must be terminated with a
nonalphanumeric character.
character array (required)
mode
Passes the password associated with the user logging identier by the GETLOG
command.
16-bit signed integer by reference (required)
Passes a value indicating whether the user logging facility suspends the
process if it cannot complete the request for service immediately:
Value
0
1
Meaning
Wait
Nowait
If it is not possible to log the transaction and mode is set to nowait,
logstatus indicates that it could not complete the request.
4-550
Command Definitions
OPENLOG
logstatus
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the call:
Value
0
1
2
3
5
6
7
8
9
12
13
15
16
Meaning
Successful
Nowait mode requested; user logging process busy
Parameter out of bounds
Request to open or write to a user logging process not running
Incorrect mode parameter passed
Request denied; user logging process suspended
Illegal capability; user logging (LG) or system supervisor (OP)
capability required
Incorrect password passed
Error while writing to the user logging le
System out of disk space; user logging cannot proceed
Out of user logging entries
End-of-le on user logging le
Invalid user logging identier
Operation Notes
The user logging facility establishes a logging buer (LOGBUFF) entry for every active process
and increments the user count only at the rst OPENLOG call. Other counters keep track of the
number of times OPENLOG and CLOSELOG are called for each user; the counter is incremented
for every OPENLOG and decremented for every CLOSELOG for each user. This ensures that
the entry in LOGBUFF is released only if it is the last CLOSELOG call (that is, call counter
= 0). The number of users and log entries are independent of the number of times the
OPENLOG/CLOSELOG intrinsics are called within an application.
Related Information
Intrinsics
Commands
Manuals
None
LOG
User Logging Programmer's Guide (32650-90027)
Command Definitions
4-551
PAUSE
NM and CM callable.
Suspends the calling process for a specied number of seconds.
Syntax
32R
PAUSE(interval);
Parameters
interval
32-bit real by reference (required)
Passes the amount of time, in seconds, that the process pauses. The value
of interval must be positive. The maximum time allowed is approximately
2,147,484 seconds (almost 25 days).
Operation Notes
BREAK or RESUME takes place without aecting the time countdown process.
Y causes the timer to countdown to restart at the beginning. It is all right if the traps
are enabled because the handler returns to PAUSE (unless the handler has called the QUIT
intrinsic.
4CNTL5
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. Insucient system table (timer request list) space.
Request denied. A negative value was specied for interval.
Related Information
Intrinsics
Commands
Manuals
4-552
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
PRINT
PRINT
NM and CM callable.
Prints character string on job/session listing device.
Syntax
CA
I16V
I16V
PRINT(message,length,controlcode);
Parameters
message
character array (required)
length
Passes the string of ASCII characters to $STDLIST.
16-bit signed integer by value (required)
controlcode
Returns the length of the character string to be passed in message. If length
is positive, the length is in half words; if negative, the length is in bytes. If
length exceeds the congured record length of the device, successive records
are written only on terminals.
16-bit signed integer by value (required)
Passes a carriage-control code.
Operation Notes
The PRINT intrinsic is limited in its usefulness; the full capability of the le system is not
available. For example, the FILE command is not allowed and some le intrinsics cannot be
used, because the lenum parameter (obtained from the FOPEN/HPFOPEN intrinsic) is not
available to PRINT intrinsic users.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
End-of-data was encountered.
Request denied. An I/O error occurred. Further error analysis through the
FCHECK intrinsic is not possible.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017) and Point-to-Point
Workstation I/O Reference Manual (30000-90250)
Command Definitions
4-553
PRINTFILEINFO
NM and CM callable.
Prints a le information display on the job/session list device.
Syntax
I16V
PRINTFILEINFO(lenum);
Parameters
lenum
16-bit signed integer by value (required)
Passes the le number of the le to be displayed.
Operation Notes
Hierarchical directories and les can be opened using FOPEN or HPOPEN intrinsic.
PRINTFILEINFO is used to display le information for any type of directory or le.
Related Information
Intrinsics
Commands
Manuals
4-554
None
None
Accessing Files Programmer's Guide (32650-90017) and Point-to-Point
Workstation I/O Reference Manual (30000-90250)
Command Definitions
PRINTOP
PRINTOP
NM and CM callable.
Prints a character string on the system console.
Syntax
CA
I16V
I16V
PRINTOP(message,length,controlcode);
Parameters
message
character array (required)
length
Passes the character string to be output. The string is limited to 72
characters, additional characters are ignored. Nonvideo-enhancing escape
sequences are stripped out.
16-bit signed integer by value (required)
controlcode
Passes the length of the output string to be transmitted. If length is positive,
the length is in half words; if negative, the length is in bytes.
16-bit signed integer by value (required)
Passes the cursor control value:
Note
Value
Meaning
0
%320
Moves the cursor to a new line after the message is printed
Does not move the cursor after the message is printed
If a null character (%000) is embedded in an array to be printed on the system
console through PRINTOP, then PRINTOP prints only the portion of the array
before the null character, regardless of the length specied.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. A physical I/O error occurred. Further error analysis
through the FCHECK intrinsic is not possible.
Command Definitions
4-555
PRINTOP
Related Information
Intrinsics
Commands
Manuals
4-556
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
PRINTOPREPLY
PRINTOPREPLY
NM and CM callable.
Prints a character string on the system console and solicits a reply.
Syntax
I16
CA
I16V I16V
length:=PRINTOPREPLY(message,length,zero,
CA
I16V
reply,maxlength);
Functional Return
length
16-bit signed integer (assigned functional return)
Passes the length of the reply from the system operator. This length
represents a half word count if maxlength is positive or a byte count if
maxlength is negative.
If maxlength is zero, then this intrinsic does not solicit a reply.
If an error occurs, the value returned is zero.
The length parameter can be zero, in which case only the standard message
prex is written on the system console . If both length and maxlength are
zero, then CCL (1) is returned.
Parameters
message
character array (required)
length
Passes the characters that are output to the system console. The character
string is limited to 50 characters, additional characters are ignored.
16-bit signed integer by value (required)
zero
The length of the output string to be transmitted. If length is positive, the
length is in half words; if negative, the length is in bytes. Do not specify a
length of >50 bytes.
16-bit signed integer by value (required)
reply
Do not specify this parameter, but maintain parameter position with a value
of 0.
character array (required)
Returns the input characters read from the system console.
Command Definitions
4-557
PRINTOPREPLY
maxlength
16-bit signed integer by value (required)
The maximum length of the message to be read into the reply parameter. If
the expected length is positive, it species a half word count; if negative, it
species a byte count. Do not specify a length of >31 bytes.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. A physical I/O error occurred. Further error analysis
through the FCHECK intrinsic is not possible.
Related Information
Intrinsics
Commands
Manuals
4-558
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
PROCINFO
PROCINFO
NM and CM callable.
Provides access to process information.
Syntax
I16
I16
I16V
PROCINFO(infoerror1,infoerror2,pin
I16V *
[,itemnum1,item1] [...] [,itemnum6,item6]);
Note
You can specify up to six itemnum,item pairs.
Parameters
error1
16-bit signed integer by reference (required)
error2
Returns a value indicating the success or failure of the intrinsic call. Refer to
Table 4-25.
16-bit signed integer by reference (required)
pin
Returns a value that supplies additional error information in error1. Refer to
Table 4-25.
16-bit signed integer by value (required)
Passes the process identication number (PIN) of the process for which
information is to be returned in the item parameter. A zero returns
information about the calling process.
itemnum
This parameter is not compatible with the pin parameter of the GETPROCINFO
intrinsic.
16-bit signed integer by value (optional)
item
Passes the item number of an information option, as dened in Table 4-26.
type varies (optional)
Returns information about the process specied by pin, as specied in
Table 4-26.
Command Definitions
4-559
PROCINFO
Table 4-25. PROCINFO Error1,Error2 Values
Error1
Description
Error2
0
Successful
0
1
Insucient capability
Index of oending itemnum
3
Required parameter address (other than
error1 ) out of bounds
Not used
4
Illegal array size
Array size passed to PROCINFO
5
Invalid itemnum
Index of oending itemnum
6
Invalid PIN; no information returned
-1
7
Unassigned PIN
-1
8
Unpaired itemnum,item parameters
Index of oending itemnum,item parameters
9
Invalid access to information
-1
10
Invalid address entered for item
Index of oending itemnum,item parameters
11
The process name cannot be represented
using the desired syntax
Index of oending itemnum,item parameters
Note
The process aborts if the error1 parameter address is illegal.
If an error condition is detected while processing an information request, the
index of the itemnum , where the oending option was located, is stored in
error2.
4-560
Command Definitions
PROCINFO
Table 4-26. PROCINFO Itemnum/Item Values
Itemnum Mnemonic
Item Description
1
I16
Process identication number (PIN) of calling process
2
I16
Process identication number (PIN) of the parent of the process specied by pin .
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
3
I16
Number of children of the process specied by pin .
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
4
I16
Number of descendants (children, grandchildren, and so on) of the process
specied by pin .
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
5
I16
Number of generations (number of levels in the process tree substructure),
including itself, of the process specied by pin .
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
Command Definitions
4-561
PROCINFO
Table 4-26. PROCINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
6
I16A
Item Description
Process identication numbers (PINs) of all children of the process specied by
pin .
A variable number of PINs are returned; item must be a 16-bit signed integer
array. The rst element of the array must be set by the calling process to
indicate the array size. The array size should include the array size element (for
example, for four PINs, the rst entry that contains the array size should be 5).
PINs are stored into the array, one PIN per element, starting with the second
element and continuing until the array is lled or all PINs are returned. If the
array is not lled, the remaining unused elements are padded with zeros.
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
7
I16A
Process identication numbers (PINs) of all descendants below children,
grandchildren, and so on) of the process specied by pin .
A variable number of PINs are returned; item must be a 16-bit signed integer
array. The rst element of the array must be set by the calling process to
indicate the array size. The array size should include the array size element (for
example, for four PINs, the rst entry that contains the array size should be 5).
PINs are stored into the array, one PIN per element, starting with the second
element and continuing until the array is lled or all PINs are returned. If the
array is not lled, the remaining unused elements are padded with zeros.
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
8
I16
Priority number in the master queue of the process specied by pin (same as Bits
(0:16) returned by GETPROCINFO intrinsic).
9
I16
State and activation information of the process specied by pin (same as Bits
(16:16) returned by GETPROCINFO intrinsic).
4-562
Command Definitions
PROCINFO
Table 4-26. PROCINFO Itemnum/Item Values (continued)
Itemnum Mnemonic
10
CA
Item Description
Program name that the process specied by pin is currently executing.
The character array for the program name must be a minimum of 28 bytes long.
The name is returned in the form le.group.account , where le is the local le
name, group is the group name, and account is the account name of the le
containing the program that the specied process is currently executing. The
name is returned left-justied with the unused locations lled with blanks.
If the calling process is executing in privileged mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process.
2. Information returned for descendants below children (grandchildren,
great-grandchildren and so on) and processes directly above the calling process
is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
12
Returns a null-terminated HFS-syntax absolute pathname that the process
specied by pin is currently executing.
On input, the rst four bytes of the buer are interpreted as a signed integer
specifying the maximum bufer size in bytes. The maximum buer size does not
include the four bytes used to represent the size.
On output, the rst four bytes of the buer represent the pathname length
excluding the null-terminator as a signed integer. The pathname is returned in
the bytes following the pathname length. Bytes beyond the null-terminator
should be considered undened.
If the maximum buer length is not correct on input, variables allocated near the
buer can be overwritten, or an error occurs. If the process name is not expressed
using HFS syntax, an error is returned in the rst four bytes of the buer.
If the calling process is executing in privilege mode, requests for information are
honored for any process. Otherwise, requests are honored as follows:
1. Complete information is returned for children of the calling process itself.
2. Information returned for descendants below children (grandchildren,
great-grandchildren, and so on) and processes directly above the calling
process is limited to itemnum s 2 through 7, 10, and 12 only. Process handling
capability is required for any user mode call unless the calling process is
requesting information about itself.
Command Definitions
4-563
PROCINFO
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. Error1 and error2 return zero.
Not returned.
Request denied. Error codes set and returned in error1 and error2.
Related Information
Intrinsics
Commands
Manuals
4-564
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
PROCTIME
PROCTIME
NM and CM callable.
Returns the accumulated CPU time for a process.
Syntax
I32
time:=PROCTIME;
Functional Return
time
32-bit signed integer (assigned functional return)
Returns the number of milliseconds that the process has been running.
Related Information
Intrinsics
Commands
Manuals
None
REPORT
Process Management Programmer's Guide (32650-90023) and Getting System
Information Programmer's Guide (32650-90018)
Command Definitions
4-565
PUTJCW
NM and CM callable.
Assigns the value of a particular job control word (JCW) in the job control word table.
Syntax
CA
U16
I16
PUTJCW(jcwname,jcwvalue,jcwstatus);
Parameters
jcwname
character array (required)
jcwvalue
Passes the name of the JCW. This array can contain up to 255 characters,
beginning with a letter and ending with a nonalphanumeric character, such as
a blank. An @ causes all executing JCWs to be set to jcwvalue.
16-bit unsigned integer by reference (required)
jcwstatus
Passes the value of the JCW.
16-bit signed integer by reference (required)
Returns the execution status:
Value
0
1
2
3
4
5
6
7
Meaning
Successful
Error, jcwname greater than 255 characters
Error, jcwname does not start with an alpha character
Error, JCW table overow (no JCW with this name exists in
table and unable to create new entry)
Error, jcwname cannot be a valid JCW value
Error, cannot assign a value to a system-reserved JCW, or a
read-only variable
Warning, standard variable reclassied as a JCW
Error, cannot reclassify predened variable
Operation Notes
If a JCW of the same name already exists in the table, only its value is entered. If no entry
exists for this name, an entry is created and its value is entered.
There are three types of JCWs in the system:
User-dened
System-dened
System-reserved
4-566
Command Definitions
PUTJCW
An attempt to assign a value to a system-reserved JCW results in an error. The
system-reserved JCWs are:
HPDATE
HPDAY
HPHOUR
HPMONTH
HPMINUTE
HPYEAR
Related Information
Intrinsics
Commands
Manuals
FINDJCW, GETJCW, SETJCW
SETJCW, SHOWJCW
Interprocess Communication Programmer's Guide (32650-90019)
and Command Interpreter Access and Variables Programmer's Guide
(32650-90011)
Command Definitions
4-567
QUIT
NM and CM callable.
Aborts the calling process.
Syntax
I16V
QUIT(num);
Parameters
num
16-bit signed integer by value (required)
Passes any integer value in the range -32767 to 32768. When executed, num
is output as part of the abort message, as follows:
ABORT: PIN = pin: by QUIT; PARM = num
PROGRAM TERMINATED IN AN ERROR STATE
Operation Notes
Aborts the calling process by:
Transmitting an abort message to the list device of the calling process.
Setting the job/session job control word (JCW) to indicate that the program terminated in
an error state.
Deleting the calling process and all of its descendants. All resources held by the deleted
processes are released. Any remaining les opened by the deleted processes are closed and
assigned the same disposition they had when opened.
In batch jobs, not using the CONTINUE command results in job termination.
This intrinsic aects the system job control word (JCW).
Related Information
Intrinsics
Commands
Manuals
4-568
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
QUITPROG
QUITPROG
NM and CM callable.
Aborts the entire user process structure.
Syntax
I16V
QUITPROG(num);
Parameters
num
16-bit signed integer by value (required)
Passes any integer value in the range 0..16383. When executed, num is
output as part of the abort message.
Operation Notes
Aborts the entire user process structure (all children of the job/session main process) by:
Transmitting an abort message to the list device of the job/session main process.
Setting the job/session job control word (JCW) to indicate that the program terminated in
an error state.
Deleting all descendants of the job/session main process (the entire user program structure).
All resources held by the deleted processes are released. Any remaining les opened by the
deleted processes are closed and assigned the same disposition they had when opened.
In batch jobs, not using the CONTINUE command terminates the job.
This intrinsic aects the system job control word (JCW).
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-569
READ
NM and CM callable.
Reads an ASCII string from $STDIN into an array.
Syntax
I16
CA
I16V
length:=READ(message,msglength);
Functional Return
length
16-bit signed integer (assigned functional return)
The length of the ASCII string that was read. If msglength is positive, the
length specied is in half words; if negative, the length specied is in bytes.
Parameters
message
character array (required)
msglength
Returns the ASCII characters that were read.
16-bit signed integer by value (required)
Note
Returns the length of message. If msglength is positive, it species the
length in half words; if negative, it species the length in bytes. When the
record is read, the rst msglength characters are input. If msglength is >=
record size of message, the entire record is transmitted.
Passing a value >message can cause user data corruption or a CCL (1)
bounds violation if the system could be corrupted by the call.
Operation Notes
Reads an ASCII string from $STDIN into an array. This is similar to calling the FREAD
intrinsic against the le $STDIN. This intrinsic is limited; full capability of the le system is
not available. For example, FILE commands are not allowed and some le intrinsics cannot
be used because the lenum parameter, obtained from the FOPEN/HPFOPEN intrinsic, is not
normally available to users of the READ intrinsic.
Basic line editing, such as cancellation of lines and backspacing, are performed automatically
by the I/O driver. If the input device is a terminal in full-duplex mode with the ECHO
facility on, or if the terminal is in half-duplex mode, the characters read are printed.
4-570
Command Definitions
READ
READ interprets the following to be end-of-le (EOF) markers when they begin in the st
column of a record:
For sessions, a colon (:).
For jobs, a colon (:) or the actual EOF.
When one of these indicators are encountered, CCG (0) is returned and no transfer occurs.
If $STDIN is redirected, only the le's actual EOF is interpreted as the valid EOF indicator.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request granted. A record with a colon in the rst column, signaling the
end-of-data or a hardware end-of-le, was encountered.
Request denied. A physical I/O error occurred. Further error analysis
through the FCHECK intrinsic is not possible.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-571
READX
NM and CM callable.
Reads an ASCII string from $STDINX into an array.
Syntax
I16
CA
I16V
length:=READX(message,msglength);
Functional Return
length
16-bit signed integer (assigned functional return)
The length of the ASCII string that was read. If msglength is positive, the
length specied is in half words; if negative, the length specied is in bytes.
Parameters
message
character array (required)
msglength
Returns the ASCII characters that were read.
16-bit signed integer by value (required)
Note
4-572
Returns the length of message. If msglength is positive, it species the
length in half words; if negative, it species the length in bytes. When the
record is read, the rst msglength characters are input. If msglength is >=
record size of message, the entire record is transmitted.
Passing a value >message can cause user data corruption or a CCL (1)
bounds violation if the system could be corrupted by the call.
Command Definitions
READX
Operation Notes
The READX intrinsic reads an ASCII string from $STDINX into an array. This is similar to
calling the FREAD intrinsic against the le $STDINX. However, the READX intrinsic is limited
in its usefulness in that the full capability of the le system is not available to you. For
example, FILE commands are not allowed. Also, you cannot use certain le intrinsics because
the lenum parameter, obtained from either the FOPEN/HPFOPEN intrinsic, is not normally
available to users of the READX intrinsic.
Basic line editing, such as cancellation of lines and backspacing, are performed automatically
by the I/O driver. If the input device is a terminal in full-duplex mode with the ECHO
facility on, or if the terminal is in half-duplex mode, the characters read are printed.
READX interprets EOD, EOF, or in a job, EOJ, JOB, or DATA as an end-of-le indicator.
If $STDIN is redirected, only the le's actual EOF is interpreted as the valid EOF indicator.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
An EOD, EOF, or in a job, EOJ, JOB, or DATA command was encountered.
Request denied. A physical I/O error occurred. Further error analysis
through the FCHECK intrinsic is not possible.
Related Information
Intrinsics
Commands
Manuals
None
None
Accessing Files Programmer's Guide (32650-90017)
Command Definitions
4-573
RECEIVEMAIL
NM and CM callable.
Receives mail from another process. Process handling (PH) capability is required.
Syntax
U16
I16V UDS
U16V
mailstatus:=RECEIVEMAIL(pin,location,waitag);
Functional Return
mailstatus
16-bit unsigned integer (assigned functional return)
Returns one of the following values:
Value
0
1
2
3
4
Meaning
Mailbox empty and waitag bit (15:1)=0.
No message collected, the mailbox contained outgoing mail
from the receiving process.
Message collected successfully.
Error occurred because an invalid pin was specied or a
bounds check failed.
Request denied, waitag specied that the receiving process
wait for mail if the mailbox is empty, but the other process
sharing the mailbox is already suspended, waiting for mail. If
both processes were suspended, neither could activate the
other, and they may be deadlocked.
Parameters
pin
16-bit signed integer by value (required)
location
The process sending the mail. If you specify a child process,pin is the process
identication number (PIN) of that process. If you specify a parent process,
pin is zero.
user-dened structure (required)
The buer where the message is written.
4-574
Command Definitions
RECEIVEMAIL
waitag
16-bit unsigned integer by value (required)
The action to be taken if the mailbox is empty. This is determined by the
setting of bit (15:1), which has the following settings:
Value
0
1
Meaning
Return immediately to the calling process.
Wait until incoming mail is ready for collection.
Operation Notes
The RECEIVEMAIL intrinsic lets a process collect mail transmitted to it by its parent or a child.
If the mailbox for the receiving process is empty, the action taken depends on the waitag
parameter specied in the RECEIVEMAIL intrinsic call. If the mailbox is currently in use by
another process, RECEIVEMAIL waits until the mailbox is free before accessing it.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The mail was collected (value 2 is returned to mailstatus ) or
the mail was not collected because the mailbox contained outgoing mail from
the receiving process (value 1 is returned to mailstatus ).
Request denied. An illegal pin parameter (value 3 is returned to mailstatus ).
Request denied. The location parameter does not allow write access on the
stack address (value 3 is returned to mailstatus ) or because both sending and
receiving processes are waiting for incoming mail, causing a deadlock (value 4
is returned to mailstatus ).
Related Information
Intrinsics
Commands
Manuals
None
None
Interprocess Communication Programmer's Guide (32650-90019)
Command Definitions
4-575
RESETCONTROL
NM and CM callable.
Reenables the subsystem break trap which allows a process to accept other subsystem break
signals.
Syntax
RESETCONTROL;
Operation Notes
RESETCONTROL must be called to reenable the subsystem break trap after a user-written
subsystem break trap handler, previously armed by XCONTRAP, has been invoked. It is
recommended that RESETCONTROL be called from outside the user-written trap handler to
eliminate recursive trap handler calls, due to multiple subsystem break signals.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The trap handling procedure was not invoked or was not
armed by a call to XCONTRAP.
Related Information
Intrinsics
Commands
Manuals
4-576
FCONTROL, FDEVICECONTROL, XCONTRAP
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
RESETDUMP
RESETDUMP
NM and CM callable.
Disables the abort stack analysis facility. Only the current process is aected.
Syntax
RESETDUMP;
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
The abort stack analysis facility was disabled prior to the RESETDUMP call and
remains disabled.
Not returned.
Related Information
Intrinsics
Commands
Manuals
HPRESETDUMP, HPSETDUMP, SETDUMP
RESETDUMP
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
4-577
SEARCH
NM and CM callable (dierences noted below).
Searches a specially-formatted array for a specied entry or name.
Syntax
I16
CA
I16V
CA
entrynum:=SEARCH(buer,length,dictionary,
@*
denition);
Functional Return
entrynum
16-bit signed integer (assigned functional return)
Returns the entry number of the name in dictionary that matches buer. If
the name specied in buer is not found, a zero is returned.
Parameters
buer
character array (required)
length
Passes the name for which the search is to be performed.
16-bit signed integer by value (required)
dictionary
denition
Passes the length, in characters, of the array buer.
character array (required)
Passes the name of the specially formatted array that is to be searched for
buer.
(NM) 32-bit address (optional)
(CM) 16-bit address (optional)
Returns the address of the command entry denition in dictionary.
Operation Notes
The SEARCH intrinsic requires a specially formatted array of sequential entries. Each entry in
the array is formatted in the following way:
byte 1
An integer that species the length (in bytes) of the entire entry. (The length
includes this byte.)
byte 2
An integer that species the length (in bytes) of the name.
bytes 3 +
A string containing the name. (This name and the name length are checked
against the search string for a match.)
bytes x +
An optional string containing a user-dened denition.
4-578
Command Definitions
SEARCH
The last entry in the array is a zero, specifying the end of the array as an entry of zero length.
The following model creates an array to expand abbreviated input (name) to its appropriate
command (denition).
5,1,"I","IN",
6,1,"O","OUT",
7,1,"S","SKIP",
7,1,"E","EXIT",
0;
In this model, the rst entry species that the entry's length is ve bytes. The name (\I")
is one byte and its denition is \IN". A 1 is returned in the entrynum signifying that the
matching name was the rst entry in the array. (If no matching entry is found, a 0 is
returned.) The address of the denition, if specied, is returned in denition of the SEARCH
intrinsic call.
Because a search is linear, the most frequently used names should appear at the beginning of
the array to ensure ecient searching.
Related Information
Intrinsics
Commands
Manuals
MYCOMMAND
None
None
Command Definitions
4-579
SENDMAIL
NM and CM callable.
Sends mail to another process. Process handling (PH) capability is required.
Syntax
U16
I16V I16V
UDS
U16V
mailstatus:=SENDMAIL(pin,length,location,waitag);
Functional Return
mailstatus
16-bit unsigned integer (assigned functional return)
Returns one of the following values:
Value
0
1
2
3
4
5
6
Meaning
Mail transmitted successfully and mailbox contained no
previous mail.
Mail was transmitted successfully and mailbox contained mail
sent previously that was overwritten by the new mail, or
contained previous incoming/outgoing mail that was cleared.
Mail not transmitted successfully; mailbox contained incoming
mail to be collected by the sending process (regardless of the
waitag setting).
Error occurred; an illegal pin parameter was specied or a
bounds check failed.
Illegal wait request; produces a deadlock.
Request denied; length exceeded the maximum mailbox size
allowed by the system.
Request denied; storage resources for the mail data segment
were not available.
Parameters
pin
4-580
16-bit signed integer by value (required)
The process to receive the mail. If you specify a child process, pin is the
process identication number (PIN) of that process. If a parent process is
specied, pin is zero.
Command Definitions
SENDMAIL
length
16-bit signed integer by value (required)
location
The length of the message, in half words, transmitted from the stack of the
sending process. If 0 is specied, the mailbox is emptied of any incoming or
outgoing mail.
user-dened structure (required)
waitag
The buer containing the message.
16-bit unsigned integer by value (required)
Action to be taken if the mailbox contains previously sent mail, as specied in
bit (15:1):
Bits
0
1
Value/Meaning
Cancel (overwrite) any mail sent previously with the current
mail.
Wait until the receiving process collects the previous mail
before sending current mail.
Operation Notes
If the receiving process mailbox contains an uncollected message from the calling process,
the action taken depends on the waitag parameter specied in the SENDMAIL call. If the
mailbox currently is being used by another process, SENDMAIL waits until the mailbox is free
and then sends the mail.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The mail was sent (value 0 or 1 is returned to mailstatus ),
or the mail was not sent because the mailbox contained incoming mail to be
collected by the sending process (value 2 is returned to mailstatus ).
Request denied. An illegal length parameter (value 5 is returned to
mailstatus ), an illegal pin parameter was specied (value 3 is returned to
mailstatus ), or storage for the mail data segment was not available (value 6 is
returned to mailstatus ).
Request denied. The length or location parameter does not allow write
access on the stack address (value 3 is returned to mailstatus ), or both
processes are waiting to send mail (value 4 is returned to mailstatus ).
Related Information
Intrinsics
Commands
Manuals
None
None
Interprocess Communication Programmer's Guide (32650-90019)
Command Definitions
4-581
SETDUMP
NM and CM callable.
Arms a call to the system debugger from a process abort.
Syntax
I16V
SETDUMP(ags);
Parameters
ags
16-bit unsigned integer (required)
This parameter is for backward compatibility with MPE V/E systems only.
Any value passed in this parameter is ignored, but a full stack trace is always
generated.
Operation Notes
If the process aborts, Debug is called with a command string that results in a full stack trace
of the CM and NM data stacks and a dump of the NM registers. This output is sent to the
standard list device.
If the process that aborts is being run from a job, the process terminates after the stack trace
and register dump are performed. If the process is being run from a session, after the stack
trace and register dump have completed, Debug stops to accept interactive commands with
I/O performed at the user terminal, provided the following conditions are met:
The abort did not occur while in system code.
The process entered the abort code through a native mode interrupt (typically caused by
arithmetic and code-related traps).
When Debug accepts interactive input, the user is free to enter any Debug command. The
user may choose to resume the process or have it terminate.
If the abort is from a stack overow, the command list is ignored, and a stack trace is sent to
the standard list device, and the process terminates. No interactive debugging is allowed.
The HPSETDUMP intrinsic is a more exible version of this intrinsic.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-582
Request granted.
Request denied. The abort stack analysis facility was already enabled before
the SETDUMP call.
Not returned.
Command Definitions
SETDUMP
Related Information
Intrinsics
Commands
Manuals
HPRESETDUMP, HPSETDUMP, RESETDUMP, STACKDUMP
SETDUMP
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
4-583
SETJCW
NM and CM callable.
Sets bits in the system job control word (JCW).
Syntax
U16V
SETJCW(jcword);
Parameters
jcword
16-bit unsigned integer by value (required)
The user-dened bit contents of the system JCW for interprocess
communication.
Bits
Value/Meaning
0:1
Reserved for the operating system
If (0:1)=1, the system outputs the following message when the
program terminates, either normally or due to an error:
PROGRAM TERMINATED IN ERROR STATE
(CIERR 976)
In batch mode, the job is terminated unless the CONTINUE
command is used. If JCW is set to exactly %140000 (bits
(0:1)=1 and (1:1)=1 only), the CIERR 976 message is replaced
by:
PROGRAM ABORTED PER USER REQUEST
(CIERR 989)
1:15
Used for any purpose.
Related Information
Intrinsics
Commands
Manuals
4-584
FINDJCW, GETJCW, PUTJCW
SETJCW, SHOWJCW
Interprocess Communication Programmer's Guide (32650-90019), Command
Interpreter Access and Variables Programmer's Guide (32650-90011), and
MPE/iX Commands Reference Manual Volumes 1 and 2 (32650-90003 and
32650-90364)
Command Definitions
SORTEND
SORTEND
NM and CM callable.
Closes the scratch le and restores the data stack to its original state.
Syntax
SORTEND;
Operation Notes
Signals the beginning of the SORT program if the SORTOUTPUT intrinsic is not called.
Required if SORTINIT is called. Call SORTEND either after all calls to the output le are
completed by the SORTINIT intrinsic, or after all calls to the SORTOUTPUT intrinsic are
completed.
Note
If you are coding a CM application, you must call SORTEND in the same
routine
in which you call the SORTINIT intrinsic. This is not the case when you code
an
NM application.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the SORT program. The value of
the failure parameter of the SORTINIT intrinsic is set to false.
Not returned.
Request denied. An error occurred during the SORT program. The value of
the failure parameter of the SORTINIT intrinsic is set to true.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-585
SORTERRORMESS
NM and CM callable.
Retrieves and prints a message if a fatal error occurs during the SORT program.
Syntax
I16V
CA
I16
SORTERRORMESS(errorcode,message,length);
Parameters
errorcode
16-bit signed integer by value
message
Returns the error number from SORTINIT in the errorparm parameter.
character array
length
Returns the text of the error message. This parameter must be at least 80
characters long.
16-bit signed integer
Returns the length of the message parameter.
Related Information
Intrinsics
Commands
Manuals
4-586
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
SORTINIT
SORTINIT
NM and CM callable.
Initiates the SORT program.
Syntax
I16A
I16A
I16V
SORTINIT(inputles,outputles,outputoption,
I16V
I32V I16V I16A
reclength,numrecs,numkeys,keys,
I16A
PROC
PROC
I16A
altseq,keycompare,errorproc,statistics,
I16
I16
I16
I16A
failure,errorparm,spaceallocation,charseq);
Parameters
inputles
16-bit signed integer array (optional)
outputles
Passes the le identication numbers of the input les to be sorted. The last
element of this array should be set to zero. If the les are opened with either
the NOBUF or MR (multirecord) access option (aoption ), the SORT program
performs the buering and blocking/deblocking. $NULL is not a valid input
le.
16-bit signed integer array (optional)
Passes the le identication number of the output le. The second array
element must be a zero, indicating the end of the array. If the les are opened
with either the NOBUF or MR (multirecord) access option (aoption ), the SORT
program performs the buering and blocking/deblocking.
Command Definitions
4-587
SORTINIT
outputoption
16-bit signed integer by value (optional)
Passes a value that determines the format of the output records:
Value
0
1
2
3
Meaning
Output record is the same as the input record (default).
Output record is a 32-bit integer whose value is the logical
(relative) record number of the record.
Output record contains only the key elds, concatenated
together with the major keys on the left, followed by the
remaining keys.
Output record is the logical record number followed by the key
elds.
reclength
16-bit signed integer by value (optional)
numrecs
Passes the maximum length of a record in characters. If you do not
specify reclength , the record length is taken from the rst le specied in
the inputles parameter. If this parameter is not specied, the inputles
parameter must be specied.
32-bit signed integer by value (optional)
numkeys
Passes the upper bound to the number of records to be sorted. If numrecs
is not specied (or if all input les are not on the disk), the value of 10,000
(32-bit integer) is used. Otherwise, the value of this parameter is derived from
the le label (the end of le number of the input les).
16-bit signed integer by value (optional)
Passes the number of keys used during the comparison of records. This
parameter can be >= 1. If the numkeys parameter is specied, the keys
parameter must be specied and the keycompare parameter cannot be
specied. Together, numkeys and keys describe the way records are sorted.
4-588
Command Definitions
SORTINIT
keys
16-bit integer array (optional)
Passes information about the keys used during comparison of records. If you
specify the keys parameter, you must specify the numkeys parameter and
must not specify keycompare . Together, keys and numkeys describe the way
records are merged.
The rst element gives the position of the rst character of the key within
the record. The second element gives the number of characters in the key.
Bits (0:8) of the third element give the ordering sequence of the records (0 for
ascending, 1 for descending). Bits (8:8) of the third element indicate the type
of data according to the following convention:
Value
0
1
2
3
4
5
6
7
8
9
11
12
Note
Meaning
8-bit unsigned integer
Twos complement (including 16-bit and 32-bit signed integer)
Floating-point (including real and long)
Packed decimal
Display trailing sign
Packed decimal with even number of digits
Display leading sign
Display leading sign separate
Display trailing sign separate
Character (using the collating sequence of charseq )
Short oating-point decimal
Floating-point decimal
The integrity of the keys array must be maintained throughout the SORT
operation. Do not change it until after the SORTEND intrinsic has been called.
Command Definitions
4-589
SORTINIT
altseq
16-bit signed integer array (optional)
Passes an alternate collating sequence. Bits (0:8) of the rst element are
specied according to the following table, where the sequence comprises the
columns and the data comprises the rows:
excess space above nonumber table|>
ASCII
ASCII
chr(255)
EBCDIC chr(1)
EBCDIC ALTSEQ
chr(2)
chr(0)
chr(255) undened
Bits (8:8) of the rst element specify one less than the total number of
characters in the collating sequence (in this instance, chr(255) or %377).
keycompare
The remaining array elements comprise the actual collating sequence
responsible for the particular SORT operation.
procedure (reserved)
errorproc
Do not specify this parameter, but maintain parameter position.
procedure (reserved)
statistics
Do not specify this parameter, but maintain parameter position.
16-bit signed integer array (optional)
Returns information on the SORT operation, as follows:
Value
1,2
3
4
5,6
7,8
9,10
11,12
4-590
Command Definitions
Meaning
Number of records sorted (32-bit integer)
Number of intermediate passes
Space available for sorting
Number of comparisons (32-bit integer)
Number of scratch le I/Os (32-bit integer)
CPU time used in milliseconds (32-bit integer)
Elapsed time in milliseconds (32-bit integer)
SORTINIT
failure
16-bit signed integer (optional)
errorparm
Returns a true value (-1) if a fatal error occurs; otherwise returns a false value
(0). The value is set after each call to SORTINPUT and SORTOUTPUT. Refer to
the discussion of condition codes.
16-bit signed integer (optional)
Returns the SORTLIB error number if an error occurs. Use the
SORTERRORMESS intrinsic to obtain the error message text.
spaceallocation 16-bit signed integer (reserved)
charseq
Do not specify this parameter, but maintain parameter position.
16-bit signed integer array (optional)
Passes language information in a two-element array. Set the rst element to
1. Set the second element to the language ID number of the native language
whose collating sequence is to be used to sort keys of type 9 (character).
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the SORT program. The value of
the failure parameter of the SORTINIT intrinsic is set to false.
Not returned.
Request denied. An error occurred during the SORT program. The value of
the failure parameter of the SORTINIT intrinsic is set to true.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-591
SORTINPUT
NM and CM callable.
Provides an alternative method of specifying how records are supplied to the SORT program.
Syntax
CA I16V
SORTINPUT(record,length);
Parameters
record
16-bit character array
length
Passes the next input data record.
16-bit signed integer
Passes the length of the record parameter value. This value should be long
enough to contain all specied keys, but not longer than the record size
specied in the reclen parameter of the SORTINIT intrinsic.
Operation Notes
Use this intrinsic only if the inputles parameter in a call to the SORTINIT intrinsic was not
used. SORTINPUT passes the input records, one at a time, to the SORT program. A call to
SORTINPUT follows a call to SORTINIT and precedes all calls to the SORTOUTPUT and SORTEND
intrinsics.
If you are coding a CM application, you must call SORTEND in the same
routine in which you call the SORTINIT intrinsic. This is not the case when
you code an NM application.
Note
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the SORT program.
Not returned.
Request denied. An error occurred during the SORT program.
Related Information
Intrinsics
Commands
Manuals
4-592
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
SORTOUTPUT
SORTOUTPUT
NM and CM callable.
Provides an alternative method of specifying how records are output from the SORT program.
Syntax
CA
I16
SORTOUTPUT( record,length);
Parameters
record
16-bit character array
length
Returns the next output record. The format of this record is specied in the
outputoption parameter of the SORTINIT intrinsic.
16-bit signed integer
Returns the length of the record parameter value. When no more records
remain, the value of this parameter is set to -1.
Operation Notes
SORTOUTPUT signals the beginning of the SORT program and receives each output record
from the SORT program into an array specied by the record parameter. SORTOUTPUT
signals the end of the input process if SORTINPUT intrinsic is called. Use SORTOUTPUT only if
the outputles parameter in a call to the SORTINIT intrinsic is not specied. If SORTINPUT
is called, then SORTOUTPUT is called only after SORTINPUT has passed all records. A call to
SORTOUTPUT always precedes a call to the SORTEND intrinsic.
Note
If you are coding a CM application, you must call SORTEND in the same
routine
in which you call the SORTINIT intrinsic. This is not the case when you code
an
NM application.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. No error occurred during the SORT program.
Not returned.
Request denied. An error occurred during the SORT program.
Command Definitions
4-593
SORTOUTPUT
Related Information
Intrinsics
Commands
Manuals
4-594
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
SORTSTAT
SORTSTAT
NM and CM callable.
Prints the SORT program statistics on $STDLIST. Call SORTSTAT after you have called the
SORTEND intrinsic.
Syntax
I16A
SORTSTAT(statistics);
Parameters
statistics
16-bit signed integer array
Returns MERGE program statistics, such as the number of records, the
number of intermediate passes, the space available in words, the number
of compares, the number of scratch le I/O operations, the CPU time in
minutes, and the elapsed time in minutes.
Related Information
Intrinsics
Commands
Manuals
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
4-595
SORTTITLE
NM and CM callable.
Prints the version number and title of the SORTLIB segment on $STDLIST.
Syntax
SORTTITLE;
Operation Notes
SORTTITLE prints the date and time from the DATELINE intrinsic. SORTTITLE can be called
any time after the system intrinsics are declared.
Related Information
Intrinsics
Commands
Manuals
4-596
HPSORT, HPMERGE
None
SORT-MERGE/XL Programmer's Guide (32650-90080)
Command Definitions
STACKDUMP
STACKDUMP
NM and CM callable (dierences noted below).
Calls the system debugger to send a stack trace to $STDLIST or to the le specied in the
formaldesig parameter. Control then returns to the calling procedure.
Syntax
(NM and CM)
CA
I16V I16V I32
STACKDUMP(formaldesig,idnumber,ags,selec);
(CM: SPL language only)
CA
I16V
I16V I32
STACKDUMP'( formaldesig,idnumber,ags,selec);
Parameters
formaldesig
character array (optional)
Passes the le name of a new output le to be opened. The name is
terminated by any nonalphanumeric character except a slash (/) or a period
(.). The same restrictions for the formaldesig parameter in the FOPEN intrinsic
apply to this parameter.
(CM: SPL language only) If the secondary entry point, STACKDUMP', is used,
the rst byte of formaldesig contains the le number that was successfully
opened prior to the call to STACKDUMP'. In this case, the le is not closed
before returning to the calling program. When a le number is passed, the
record length must be between 64 bytes and 512 bytes and write access must
be allowed for the le.
idnumber
Default: Dump is sent to $STDLIST.
16-bit signed integer by value (optional)
If the intrinsic fails due to a le system error, the le system specic error
number of the failure is returned here. Any value passed into the intrinsic
through this parameter is ignored.
Command Definitions
4-597
STACKDUMP
ags
16-bit unsigned integer by value (optional)
selec
This parameter is provided for compatibility with MPE V/E. If it is present,
it is ignored and has no eect.
32-bit integer array by reference (optional)
This parameter is provided for compatibility with MPE V/E. If it is present
in the intrinsic call, it is ignored and has no eect.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. An invalid address for the location of the formaldesig
parameter was detected.
Request denied. File system error occurred during opening, writing to, or
closing the le. The le error number is returned in idnumber .
Related Information
Intrinsics
Commands
Manuals
4-598
DEBUG, HPDEBUG, HPRESETDUMP, HPSETDUMP, SETDUMP
SETDUMP
MPE/iX System Debug Reference Manual (32650-90013)
Command Definitions
STARTSESS
STARTSESS
NM and CM callable.
Initiates a session on the specied terminal. Programmatic sessions (PS) capability is
required.
Syntax
I16V
CA
I16 I32
I16A
STARTSESS(ldev,logonstring,jsid,jsnum,jsstatus);
Parameters
ldev
16-bit signed integer by value (required)
The logical device number of the target terminal (the terminal on which the
session is to be created). The target terminal must be a real physical device,
free and available to the system, job-accepting, and hardwired. In addition,
the target terminal must be congured as TYPE 16, and SUBTYPE 0 or SUBTYPE
4.
logonstring
The target terminal must be set to the congured baud rate, since there is no
baud rate sensing by STARTSESS.
character array (required)
Passes the logon string required to initiate the session on the terminal
specied by ldev. The rst characters in the string should be the session
name, if specied, or the user name if no session name is assigned.
Passwords must be supplied in logonstring. (There is no prompting for
passwords on the target terminal.) If passwords are required but not supplied
in logonstring, STARTSESS fails.
You must place a carriage-return character (%15) in the element following the
last valid character of logonstring.
jsid
The logonstring parameter is a superset of the HELLO command syntax and
includes a new option, nowait. The nowait option allows you to override the
requirement of a 4Return5 key entered at the target terminal.
16-bit signed integer by reference (required)
Returns the value 1, indicating that jsnum is a session number.
Command Definitions
4-599
STARTSESS
jsnum
32-bit signed integer by reference (required)
jsstatus
Returns a number uniquely identifying the session that was created on the
target terminal.
16-bit signed integer array (required)
Returns a two-element array containing status information. The second
element is reserved for
the operating system. The rst element returns the status information, refer
to Table 4-27.
Table 4-27. STARTSESS Status Returns
Status Value
Meaning
0
Successful
1411
Logon failed due to IDD overow
1412
Logon failed due to JMAT overow
1424
Missing or invalid user name in logonstring
1426
Missing or invalid account name in logonstring
1431
Specied session user lacks interactive access (IA) capability
1436
No such group in the account
1437
No such account in the system
1438
No such user in the account
1439
User lacks a home group, and a group was not specied in logonstring
1444
Password required but not specied in logonstring
-1451
Ignored delimiter
-1452
Unknown parameter found in logonstring ; ignored
-1458
Bad TERMTYPE specied in logonstring ; default used
-1459
Invalid PRI specied in logonstring ; default used
-1461
HIPRI then INPRI specied; INPRI used
-1462
INPRI too low; lowest valid INPRI used
-1463
INPRI too high; highest valid INPRI used
-1464
INPRI then HIPRI specied; HIPRI used
-1465
OUTCLASS specied; ignored
-1473
RESTART specied; ignored
-1479
Invalid time specied in logonstring ; no time limit is used
4-600
Command Definitions
STARTSESS
Table 4-27. STARTSESS Status Returns (continued)
Status Value
Meaning
7000
The LDEV is out of range
7001
The LDEV must not be virtual
7002
The device specied by LDEV is not a terminal
7003
The LDEV is not free
7004
The LDEV is not job-accepting
7005
The LDEV is in diagnostic mode
7006
The LDEV terminal is down
7007
Down pending on LDEV
7008
ldev specied not a real device
7009
Caller requires programmatic sessions (PS) capability
7010
Semicolon (;) delimiter is missing
7011
The LDEV is not a valid integer
7012
The LDEV cannot be a negative number
7014
Session was aborted before logging on
7015
Logon failed because system is at its session limit
7016
Logon failed because the session's INPRI was <= system jobfence
7017
Logon failed because the system was unable to obtain a PCB entry for the system
process
7018
Logon failed because the system was unable to obtain a DST entry for the session's
data stack
7019
Logon failed because the system was unable to obtain a DST entry for the session's JIT
7020
Logon failed because the system was unable to obtain a DST entry for the session's
JDT
7021
Logon failed because the system was unable to obtain a le DST entry
7022
Logon failed because the system was unable to obtain an entry for the session in the
JPCNT table
7023
Logon failed because the system was unable to obtain the XDD entry for the output
device
7024
Logon failed because the system was unable to obtain the XDD entry for the input
device
Command Definitions
4-601
STARTSESS
Table 4-27. STARTSESS Status Returns (continued)
Status Value
Meaning
7025
Unknown error occurred. This happens only in the case of an illegal call from one
internal procedure to another internal procedure when passing the error number
7026
Unable to allocate $STDIN, or logon failed because of a failure to open $STDIN
7027
Unable to allocate $STDLIST , or logon failed because of a failure to open $STDLIST
7029
Logon failed because the session's account is out of CPU time
7030
Logon failed because the session's account is out of connect time
7032
Logon failed because account or user lacks IA capability
7033
Logon failed because the session's logon group is out of CPU time
7034
Logon failed because the session's logon group is out of connect time
7035
Logon string was not terminated with a carriage-return character (%15)
7036
The LDEV has an invalid type and subtype for a programmatic session
7039
Internal programmatic session error
7040
Unable to allocate $STDERR, or logon failed because of a failure to open $STDERR
7042
Group is not specied, and there is no default home group
Note
4-602
Error messages with numbers in the 10000 range are generally Command
Interpreter errors and should be looked up in the MPE/iX Error Message
Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and 32650-90368).
Command Definitions
STARTSESS
Operation Notes
The terminal on which the session is to be created must be available; no other user may be
logged on. The target terminal is not speed-sensed, so it must be set at the congured baud
rate.
When the session is created, nothing is printed to the terminal until you press the 4Return5 key
on the selected terminal (unless you specify nowait). To override the need for a 4Return5, you
can enter the NOWAIT keyword parameter with the logon string when invoking the STARTSESS
intrinsic. For example, passing the following logon string to STARTSESS starts a session and
logon immediately without waiting for a 4Return5:
MANAGER/password.SYS;NOWAIT
Never specify the NOWAIT option in the logon string without rst ensuring that the target
terminal is turned on and set at the default baud rate. If the target terminal is the system
console and nowait is specied, then you must have system manager (SM) capability. All
other valid terminals can be specied with only programmatic sessions (PS) capability.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-603
SUSPEND
NM and CM callable.
Suspends a process. Process handling (PH) capability is required.
Syntax
U16V I16V
SUSPEND(allow,rin);
Parameters
allow
16-bit unsigned integer by value (required)
Passes the anticipated source of the call and, later, reactivates the process, as
indicated by bits (14:1) and (15:1):
Bits
Value/Meaning
14:1
0
Process does not expect to be activated by its parent
1
Process expects to be activated by its parent
Child activation bit:
15:1
Parent activation bit:
0
1
Note
Process does not expect to be activated by one of its
children
Process expects to be activated by one of its children
If the process is running with only process handling (PH) capability, at least
one of these bits must = 1.
If (14:1)=1 and (15:1)=1, either the parent or a child can activate the
suspended process.
rin
Bits (0:14) are reserved for the operating system.
16-bit signed integer by value (optional)
Passes the resource identication number (RIN). If rin is specied, it
represents a local RIN that is locked by the process but is released when
this process is suspended. This facility can be used to synchronize processes
within the same job.
4-604
Command Definitions
SUSPEND
Operation Notes
When SUSPEND is executed, the calling process relinquishes its access to the CPU until
reactivated by an ACTIVATE intrinsic call. The calling process must specify the anticipated
source of the ACTIVATE call (its parent or a child process). When the process is reactivated, it
begins execution with the instruction immediately following the SUSPEND call.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. The allow parameter is not valid, the specied RIN is not
owned by this process, or the specied RIN was not locked.
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-605
SWITCHDB
CM callable only.
Switches the DB register pointer. Privileged mode (PM) capability is required.
Syntax
U16
O-P
U16V
logindex:=SWITCHDB(index)
Functional Return
logindex
16-bit unsigned integer (assigned functional return)
Returns the logical index of the data segment indicated by the previous DB
register setting, allowing this setting to be restored later. If the previous DB
setting indicated the stack, a zero is returned.
Parameters
index
16-bit unsigned integer by value (required)
Passes the logical index of the data segment where the DB register is to
be switched (obtained through the GETDSEG intrinsic). The value specied
is checked to ensure that the process has acquired access to the segment
previously. For an extra data segment, a positive, nonzero integer must be
specied. To switch to the stack segment, a zero must be specied.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An illegal data segment was specied.
Related Information
Intrinsics
Commands
Manuals
4-606
GETDSEG
None
Introduction to MPE XL for MPE V Programmers (30367-90005)
Command Definitions
TERMINATE
TERMINATE
NM and CM callable.
Releases all resources held by the process and its descendants are released. All remaining les,
opened by the process and its descendants, are closed and assigned the same disposition they
had when opened.
Syntax
TERMINATE;
Related Information
Intrinsics
Commands
Manuals
None
None
Process Management Programmer's Guide (32650-90023)
Command Definitions
4-607
TIMER
NM and CM callable.
Returns system timer information.
Syntax
I32
count:=TIMER;
Functional Return
count
32-bit signed integer (assigned functional return)
The actual millisecond count since the midnight preceding the last system
coldload.
Operation Notes
The resolution of the system timer is one millisecond; readings taken within a one-millisecond
period can be identical. The system timer is reset to zero every 24-days at 12:00 midnight. If
using the TIMER intrinsic to compute elapsed time, correct for this condition by:
Subtracting the current count from the previous count.
If the result is negative, add 2,073,600,000 (number of milliseconds in 24 days).
Related Information
Intrinsics
Commands
Manuals
4-608
None
None
Getting System Information Programmer's Guide (32650-90018)
Command Definitions
UNLOADPROC
UNLOADPROC
NM and CM callable.
Dynamically unloads a compatibility mode (CM) segmented library (SL) procedure.
Syntax
I16V
UNLOADPROC( procid);
Parameters
procid
16-bit signed integer by value (required)
Passes the procedure's identity number, which was obtained from the
LOADPROC call.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Not returned.
Request denied. An invalid procid was specied.
Related Information
Intrinsics
Commands
Manuals
None
None
Switch Programming Guide (32650-90014)
Command Definitions
4-609
UNLOCKGLORIN
NM and CM callable.
The UNLOCKGLORIN intrinsic unlocks a global resource identication number (RIN) that was
locked with the LOCKGLORIN intrinsic.
Syntax
I16V
UNLOCKGLORIN(rinnum);
Parameters
rinnum
16-bit signed integer by value (required)
Passes the number of any RIN locked by the calling process. If rinnum does
not specify a RIN locked by the calling process, no action is taken.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. This RIN was not locked by this process.
Request denied. The specied RIN was not allocated.
Related Information
Intrinsics
Commands
Manuals
4-610
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
UNLOCKLOCRIN
UNLOCKLOCRIN
NM and CM callable.
The UNLOCKLOCRIN intrinsic unlocks a local resource identication number (RIN) that was
locked by the LOCKLOCRIN intrinsic.
Syntax
I16V
UNLOCKLOCRIN(rinnum);
Parameters
rinnum
16-bit signed integer by value (required)
Passes the locked RIN, designated by an integer from 1 to the value specied
in the rincount parameter of the GETLOCRIN intrinsic call.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted.
Request denied. The RIN specied is not locked by the calling process.
Request denied. The specied RIN is not allocated to this process.
Related Information
Intrinsics
Commands
Manuals
None
None
Resource Management Programmer's Guide (32650-90024)
Command Definitions
4-611
WHO
NM and CM callable.
Returns the access mode and attributes of the user calling the intrinsic.
Syntax
U16 I32
I32
CA
WHO(mode,capability,localattr,username,
CA
CA
CA
U16
groupname,acctname,homename,term);
Parameters
mode
16-bit unsigned integer by reference (optional)
Returns the current user's access mode. In this half word, the bits have the
following meanings:
Bits
Value/Meaning
15:1
0
14:1
12:2
0:12
4-612
Command Definitions
The job/session input le and job/session list le are not
interactive.
1
The job/session input le and job/session list le form an
interactive pair. A person responding through the input
device can establish a dialog with a program that displays
information on the list device.
0
The job/session input le and job/session list le are not
duplicative.
1
The job/session input le and job/session list le form a
duplicative pair. Images on the input device are
duplicated automatically on the list device.
00 Not used.
01 The user is accessing the system through a session.
10 The user is accessing the system through a job.
11 Not used.
Reserved for the operating system
WHO
capability
32-bit signed integer by reference (optional)
Returns the user's le access attributes, user attributes, and capability class
attributes if the appropriate bit = 1. The high-order half word indicates
le access attributes and user attributes; the low-order half word indicates
possession of capability-class attributes. The signicance of these bits is as
follows:
Bits
Value/Meaning
0:1
1:1
2:1
3:1
4:1
5:1
6:1
7:1
8:1
9:4
13:1
14:1
15:1
16:7
23:1
24:1
25:1
26:2
28:1
29:1
30:1
31:1
System manager (SM)
Account manager (AM)
Account librarian (AL)
Group librarian (GL)
Diagnostician (DI)
System supervisor (OP)
Volume set creation (CV)
Volume set usage (UV)
User logging (LG)
Reserved for the operating system
Communications system (CS)
Nonshareable devices (ND)
Save les (SF)
Reserved for the operating system
Batch access (BA)
Interactive access (IA)
Privileged mode (PM)
Reserved for the operating system
Multiple RINs (MR)
Reserved for the operating system
Extra data segments (DS)
Process handling (PH)
Command Definitions
4-613
WHO
localattr
32-bit signed integer by reference (optional)
username
Returns the local attributes of the user, as dened by a user with the account
manager attribute.
character array (optional)
groupname
Returns the user's name in an 8-character array.
character array (optional)
acctname
Returns the name of the user's logon group in an 8-character array.
character array (optional)
homename
Returns the name of the user's logon account in an 8-character array.
character array (optional)
term
Returns the name of the user's home group in an 8-character array. If a home
group is not assigned, this array is lled with blanks.
16-bit unsigned integer by reference (optional)
Returns the logical device number of the job/session input device. If this is
a spooled (STREAM) batch job, then the logical device number is the virtual
device.
A virtual device simulates a spooling device. Users cannot own the actual
spooling device, so the virtual device allows users access to spooling. Each
virtual device is temporarily assigned a logical device number for the duration
of the input or output spooling process. Since the same logical device
number can be reassigned to another virtual device with dierent physical
characteristics, such as page length, the virtual device is not permanently
congured in the system conguration. You can also obtain the logical device
number of the virtual device with FFILEINFO.
Related Information
Intrinsics
Commands
Manuals
4-614
None
None
Getting System Information Programmer's Guide (32650-90018) and
Point-to-Point Workstation I/O Reference Manual (30000-90250).
Command Definitions
WRITELOG
WRITELOG
NM and CM callable.
Writes database and subsystem le records to the user logging le. User logging (LG) or
system supervisor (OP) capability is required.
Syntax
I32 U16A I16 I16
I16
WRITELOG(index,data,length,mode,logstatus);
Parameters
index
32-bit signed integer by reference (required)
data
Passes your access to the user logging system. This is the value returned in
the index parameter of the OPENLOG intrinsic.
16-bit unsigned integer array (required)
length
Passes the information to be logged. A log record contains 128 half words
of which 119 are available for writing data. The most ecient use of log le
space is to structure arrays with lengths in multiples of 119 half words.
16-bit signed integer by reference (required)
mode
Passes the length of the data in data . A positive value indicates half words;
a negative value indicates bytes. If the length is greater than 119 half words
or 238 bytes, the information in data is divided into two or more physical log
records.
16-bit signed integer by reference (required)
Passes a value indicating whether the user logging facility will suspend the
process if it cannot complete the request for service immediately. If it is not
possible to log the transaction and mode is set to nowait, the WRITELOG
intrinsic indicates through logstatus that it could not complete the request.
Value
0
1
2
Meaning
Wait
Nowait
Write the logging buer to the disk log le (disk logging) or the
disk buer le (serial logging) at the rst opportunity.
Command Definitions
4-615
WRITELOG
logstatus
16-bit signed integer by reference (required)
Returns one of the following values, indicating the success/failure of the call:
Value
0
1
2
4
5
9
12
14
15
Meaning
Successful
Nowait requested, user logging process busy
Parameter out of bounds
Incorrect index parameter passed
Incorrect mode parameter passed
Error occurred while writing
System out of disk space; user logging cannot proceed
Invalid access
End-of-le on user log le
Related Information
Intrinsics
Commands
Manuals
4-616
BEGINLOG, ENDLOG
None
User Logging Programmer's Guide (32650-90027)
Command Definitions
XARITRAP
XARITRAP
NM and CM callable (dierences noted below).
Arms or disarms the user-written arithmetic trap handling procedure.
Syntax
I*V I32V
I32
I32
XARITRAP(mask,plabel,oldmask,oldplabel);
Note
By default, all traps except IEEE oating-point exceptions are enabled, and
the system trap handler is armed. Many oating-point operations result in an
inexact result. Most compiler libraries doing oating-point operations result in
an inexact trap if the IEEE inexact result trap is enabled. Therefore, enable
the IEEE inexact result trap only if absolutely necessary.
Parameters
mask
(NM) 32-bit signed integer by value (required)
(CM) 16-bit signed integer by value (required)
Determines which trap conditions, if enabled, invoke the user-written software
trap handler, and which do not.
Value
1
0
Meaning
Corresponding trap condition is armed
Corresponding trap condition is disarmed
The bits and their associated arithmetic errors are:
(NM)
Command Definitions
4-617
XARITRAP
4-618
Bits
Value/Meaning
31:1
30:1
29:1
28:1
27:1
26:1
25:1
24:1
23:1
22:1
21:1
3000 mode oating-point divide by zero
Integer divide by zero
3000 mode oating-point underow
3000 mode oating-point overow
Integer overow
3000 mode double-precision overow
3000 mode double-precision underow
3000 mode double-precision divide by zero
Decimal overow
Invalid ASCII digit
Invalid decimal digit
Command Definitions
XARITRAP
Bits
Value/Meaning
19:2
18:1
17:1
16:1
15:1
14:1
13:1
12:1
11:1
10:1
9:1
8:1
7:1
1:6
0:1
Reserved for the operating system
Decimal divide by zero
IEEE oating-point inexact result
IEEE oating-point underow
IEEE oating-point overow
IEEE oating-point divide by zero
IEEE oating-point invalid operation
Range errors
Software-detected NIL pointer reference
Software-detected misaligned result of pointer arithmetic or
error in conversion from long pointer to short pointer
Unimplemented condition traps
Paragraph stack overow
3000 mode packed decimal error
Reserved for the operating system
Assertion trap
Bits
Value/Meaning
15:1
14:1
13:1
12:1
11:1
10:1
9:1
8:1
7:1
6:1
5:1
4:2
2:1
3000 mode oating-point divide by zero
Integer divide by zero
3000 mode oating-point underow
3000 mode oating-point overow
Integer overow
3000 mode double-precision overow
3000 mode double-precision underow
3000 mode double-precision divide by zero
Decimal overow
Invalid ASCII digit
Invalid decimal digit
Reserved for the operating system
Decimal divide by zero
(CM)
Command Definitions
4-619
XARITRAP
Note
The following apply to the preceding trap conditions represented in the mask:
NM supports IEEE and 3000 mode formats. Both execute in NM, but
3000 mode performs Hewlett-Packard 3000 type manipulations. Since it is
possible to use both formats during program execution, there are separate
bits in the mask for enabling/disabling traps of these formats.
Some error conditions specied here are not strictly arithmetic traps (for
example, range errors, nil pointers, and paragraph stack overow). However,
many arithmetic traps are caught by reserved instructions that raise the
conditional traps. For this reason, all are enabled/disabled by XARITRAP.
Some instructions that raise conditional traps are reserved to indicate the
above trap conditions. A nonreserved instruction is one not generated by
a compiler. If a nonreserved instruction causes a conditional trap, it is
reported as an unimplemented condition trap. Only assembly language
programmers can generate such a trap.
plabel
(NM) 32-bit signed integer by value (required)
(CM) 16-bit signed integer by value (required)
oldmask
oldplabel
Passes the address of the trap handling procedure. If the value is 0, the
user-written arithmetic trap handler is disabled.
(NM) 32-bit signed integer by reference (required)
(CM) 16-bit signed integer by reference (required)
Returns the value of the previous mask .
(NM) 32-bit signed integer by reference (required)
(CM) 16-bit signed integer by reference (required)
Returns the plabel of the process's previous arithmetic trap handler. If no
plabel was previously congured, 0 is returned.
4-620
Command Definitions
XARITRAP
Operation Notes
This trap can be armed for any combination of events; at any given time, there is only one
user-written trap handler for all armed traps.
There is a dierence between arming and enabling traps:
Enabling a trap means that the occurrence of a trap condition is not ignored.
Arming a trap is required so that, on a trap condition, a user-written routine is invoked and
can take appropriate recovery actions.
The following summarizes what can occur when an arithmetic trap condition arises:
If a trap is both enabled and armed, the user-written trap handler is invoked whenever a
trap condition occurs.
If a trap is enabled but not armed, one of two situations applies:
If a Pascal XL TRY statement is executed, control is passed to the RECOVER block by
doing an ESCAPE.
If a Pascal XL TRY statement is executed, an error message is output and the process
aborts.
If a trap is disabled, irrespective of whether it is armed, the trap is ignored, and execution
of the process continues without any interruption.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. The desired traps are now armed.
Request granted. All traps are now disarmed.
Not returned.
Related Information
Intrinsics
Commands
Manuals
None
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
4-621
XCONTRAP
NM and CM callable (dierence noted below).
Arms or disarms user-written subsystem break trap handling procedure.
Syntax
I*V
I*
XCONTRAP(plabel,oldplabel);
Any user trap handler cannot perform a GOTO out of that procedure.
Performing an ESCAPE (Pascal) or completing the trap handling procedure
are the only valid ways to return. The state of the process and the program
results are not predictable after a non-local GOTO statement.
Note
Parameters
plabel
(NM) 32-bit signed integer by value (required)
(CM) 16-bit signed integer by value (required)
The plabel of the subsystem break trap handling procedure. It can be either
an NM or a CM plabel. If the value is 0, the subsystem break trap handler is
disarmed for the process.
Obtaining external plabels for the NM trap handling procedure depends on
the programming language. In Pascal/XL, for example, obtain the plabel by
using the waddress function. Supply the name of your subsystem break trap
handler as an argument to waddress.
To pass a CM plabel, set it up as follows:
1. Obtain the 16-bit external CM plabel of the CM subsystem break trap
handler. One way to do this is by using the LOADPROC intrinsic.
2. Pass this 16-bit plabel in the following 32-bit format:
(NM)
Bits
31:1
30:1
29:1
16:13
0:16
4-622
Command Definitions
Value/Meaning
Set to 1
Set to 0
Set to 1
Set to 0
16-bit external CM plabel
XCONTRAP
(CM)
Bits
0:16
oldplabel
Value/Meaning
16-bit external CM plabel
(NM) 32-bit signed integer passed by reference (required)
(CM) 16-bit signed integer passed by reference (required)
Returns the plabel of the process's previous subsystem break trap handler.
It can be either a CM or NM plabel, as described above. If no plabel was
previously congured, oldplabel returns 0.
Operation Notes
Call XCONTRAP to arm a user-written subsystem break trap handling procedure. This trap
handler is invoked when an enabled subsystem break signal is received during an interactive
session. Calling XCONTRAP from a job results in an error.
On most terminals, transmit the subsystem break signal by pressing 4CTRL5Y (the default for
sending a subsystem break signal). Subsystem break traps are also referred to as control-Y
traps.
Only one process in a session can receive a subsystem break trap at any one time. The
process that called XCONTRAP most recently receives the next subsystem break trap. Once
a process has received a subsystem break trap, it cannot receive another until it calls the
RESETCONTROL intrinsic to reenable the subsystem break trap. Only processes running in a
session can enable subsystem break traps. The trap handler can be any procedure in the
program or in the libraries to which the program is bound. The subsystem break trap handler
has no parameters.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
Request granted. Trap enabled.
Request granted. Trap disabled.
Request denied. An illegal plabel or XCONTRAP was called from a job.
Related Information
Intrinsics
Commands
Manuals
FCONTROL, FDEVICECONTROL, RESETCONTROL
None
Trap Handling Programmer's Guide (32650-90026) and Point-to-Point
Workstation I/O Reference (30000-90250)
Command Definitions
4-623
XLIBTRAP
NM and CM callable (dierences noted below).
Enables or disables a user-written software library trap handling procedure.
Syntax
I*V
I*
XLIBTRAP(plabel,oldplabel);
Any user trap handler cannot perform a GOTO out of that procedure.
Performing an ESCAPE (Pascal) or completing the trap handling procedure
are the only valid ways to return. The state of the process and the program
results are not predictable after a non-local GOTO statement.
Note
Parameters
plabel
(NM) 32-bit signed integer by value (required)
(CM) 16-bit signed integer by value (required)
oldplabel
Passes the external-type label of the trap handling procedure. If the value is
0, the trap handler is disabled.
(NM) 32-bit signed integer by reference (required)
(CM) 16-bit signed integer by reference (required)
Returns the plabel of the process's previous software library trap handler. If
no plabel was previously congured, 0 is returned.
Operation Notes
When a program begins execution, the user-written software library trap handler is disabled
automatically. When enabled by the XLIBTRAP intrinsic, and subsequently activated by an
error, the user-written software library trap handler assumes control.
This trap handler can be enabled or disabled by calling the XLIBTRAP intrinsic.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-624
Request granted. Trap enabled.
Request granted. Trap disabled.
Request denied. An illegal plabel was specied.
Command Definitions
XLIBTRAP
Related Information
Intrinsics
Commands
Manuals
None
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
4-625
XSYSTRAP
NM and CM callable (dierences noted below).
Enables or disables a user-written system trap handling procedure.
Syntax
I*V
I*
XSYSTRAP(plabel,oldplabel);
Any user trap handler cannot perform a GOTO out of that procedure.
Performing an ESCAPE (Pascal) or completing the trap handling procedure
are the only valid ways to return. The state of the process and the program
results are not predictable after a non-local GOTO statement.
Note
Parameters
plabel
(NM) 32-bit signed integer by value (required)
(CM) 16-bit signed integer by value (required)
oldplabel
Passes the external-type label of the trap handling procedure. If the value is
0, the trap handler is disabled.
(NM) 32-bit signed integer by reference (required)
(CM) 16-bit signed integer by reference (required)
Returns the plabel of the process's previous software library trap handler. If
no plabel was previously congured, 0 is returned.
Operation Notes
When a program begins execution, the user-written system trap handler is disabled
automatically. When enabled by the XSYSTRAP intrinsic, and subsequently activated by an
error, the user-written system trap handler assumes control.
The trap handler can be enabled or disabled by calling the XSYSTRAP intrinsic.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-626
Request granted. Trap enabled.
Request granted. Trap disabled.
Request denied. An illegal plabel was specied.
Command Definitions
XSYSTRAP
Related Information
Intrinsics
Commands
Manuals
None
None
Trap Handling Programmer's Guide (32650-90026)
Command Definitions
4-627
ZSIZE
NM and CM callable.
Alters current DB to Z area of the compatibility mode (CM) stack.
Syntax
I16
I16V
newsize:=ZSIZE(size);
Functional Return
newsize
16-bit signed integer (assigned functional return)
Passes the size, in half words (CM words) actually granted.
Parameters
size
16-bit signed integer by value (required)
Passes the desired register value of Z, relative to DB. This is the number of
half words (CM words) from DB to Z. This value must be >=0.
Operation Notes
When called from programs running in NM, only the CM stack is aected. Programmatic
expansion and contraction of the NM stack is not necessary.
Allows an NM program to alter the size of the current DB to Z area of the CM stack by
adjusting the register oset of the Z address from the DB address (DB to Z).
Increases the Z address (CM stack expands) or decreases the Z address (CM stack contracts).
If the Z to DB area size requested exceeds the maximum size permitted for the DL to Z (CM
stack) area, only the maximum size allowed is granted.
All changes to the DB to Z area are made in increments or decrements of 128 half words (CM
words); the size granted may dier from the size requested.
Condition Codes
CCE (2)
CCG (0)
CCL (1)
4-628
Request granted.
Request granted. The requested size exceeded the maximum limits of the
DL to Z (CM stack) area. The maximum limit is granted, and the value is
returned in newsize .
An illegal size parameter, less than (S - DB) + 64 half words was specied.
The minimum value is assigned by default.
Command Definitions
ZSIZE
Related Information
Intrinsics
Commands
Manuals
None
None
Programmer's Skills Migration Guide (30367-90005).
Command Definitions
4-629
Index
3
32-bit binary, convert from ASCII string number
DBINARY, 4-53
32-bit binary number, convert to ASCII string
DASCII, 4-50
A
Abort calling process
QUIT, 4-568
Abort entire user process structure
QUITPROG, 4-569
Abort errors, 2-12
ABORTSESS
Abort specied job/session, 4-2
Intrinsic, 4-2
Abort specied job/session
ABORTSESS, 4-2
Abort stack analysis facility, disable
RESETDUMP, 4-577
Accept another CONTROL-Y signal
RESETCONTROL, 4-576
Access, close user logging facility
CLOSELOG, 4-32
Access, establish for le on device
HPFOPEN, 4-331
Access le, predene characteristics
FOPEN, 4-189
Access le, terminate
FCLOSE, 4-79
Access information returned, le
FGETINFO, 4-155
Accessing les, 1-1
Access job and session information
JOBINFO, 4-452
Access message catalogs
GENMESSAGE, 4-267
Access message facility and output messages
CATREAD, 4-25
Access mode, control of les/devices
FSETMODE, 4-247
Access system services, 1-1
Access to process information
PROCINFO, 4-559
Access to User Logging facility
OPENLOG, 4-550
acquire local RINs
GETLOCRIN, 4-278
ACTIVATE
Activate new process, 4-4
Activate suspended process, 4-4
Intrinsic, 4-4
Activate new process
ACTIVATE, 4-4
Activate suspended process
ACTIVATE, 4-4
Activation call for process, return source
GETORIGIN, 4-279
Adjust directory space
ADJUSTUSLF, 4-6
ADJUSTUSLF
Adjust directory space, 4-6
Intrinsic, 4-6
Alignment, parameters, 2-2
Allocation to job, free local RINs
FREELOCRIN, 4-240
ALMANAC
Intrinsic, 4-8
Return numeric date information, 4-8
ALTDSEG
Alter size of extra data segment, 4-10
Intrinsic, 4-10
Alter DB to Z area of compatibility mode stack
ZSIZE, 4-628
Altering les, 1-1
Alter size of extra data segment
ALTDSEG, 4-10
Application message catalog le, close
CATCLOSE, 4-22
Application message catalog, open
CATOPEN, 4-23
Arithmetic trap, enable/disable
ARITRAP, 4-12
HPENBLTRAP, 4-316
Arithmetic trap handling procedure, arm/disarm
XARITRAP, 4-617
ARITRAP
Collectively enables/disables arithmetic traps,
4-12
Intrinsic, 4-12
Arm/disarm arithmetic trap handling procedure
XARITRAP, 4-617
Index-1
Arm/disarm software library trap handling
procedure
XLIBTRAP, 4-624
Arm/disarm subsystem break trap handling
procedure
XCONTRAP, 4-622
Arm/disarm system trap handling procedure
XSYSTRAP, 4-626
Arm system debugger call from process abort
HPSETDUMP, 4-401
Arm system debugger from process abort
SETDUMP, 4-582
Array, search for specied entry/name
SEARCH, 4-578
ASCII
Convert 16-bit binary to numeric ASCII string,
4-15
Intrinsic, 4-15
ASCII string conversion to EBCDIC
CTRANSLATE, 4-48
ASCII string, convert from 32-bit binary number
DASCII, 4-50
ASCII string, convert to 16-bit binary
BINARY, 4-19
ASCII string number, convert to 32-bit binary
DBINARY, 4-53
ASCII string, read $STDIN into array
READ, 4-570
ASCII string, read $STDINX into array
READX, 4-572
Assign system-dened les and create process
CREATEPROCESS, 4-43
Assign value of JCW in JCW table
PUTJCW, 4-566
Attribute, retrieve session-level
HPCIGETVAR, 4-301
B
BEGINLOG
Intrinsic, 4-17
Mark beginning of user logging transaction,
4-17
BINARY
Convert number from ASCII string to 16-bit
binary, 4-19
Intrinsic, 4-19
Binary conversion, 16-bit to numeric ASCII
string
ASCII, 4-15
Binary oating-point formats, convert data
HPFPCONVERT, 4-364
Break mode, place session in
CAUSEBREAK, 4-28
Index-2
C
CALENDAR
Intrinsic, 4-21
Return calendar date, 4-21
Calendar date, format
FMTCALENDAR, 4-185
FMTDATE, 4-187
Call description, intrinsic, 2-3
Calling intrinsics, 2-1
Calling process, abort
QUIT, 4-568
Calling process, delete
TERMINATE, 4-607
Calling process, set condition code
HPSETCCODE, 4-399
Calling process, suspend for specied time
PAUSE, 4-552
Calls
Errors, intrinsic, 2-8
Intrinsics, 2-1
Capabilities required by intrinsics, 2-13
Capability
Data segment management (DS), 2-14
Intrinsic, 2-13
Multiple resource identication number (MR),
2-14
Nonshareable device (ND), 2-14
Privileged mode (PM), 2-3, 2-15
Process handling (PH), 2-15
Programmatic sessions (PS), 2-15
System supervisor (OP), 2-14
User logging (LG), 2-14
Capability checks, 2-14
Catalog le, close application message
CATCLOSE, 4-22
CATCLOSE
Close specied application message catalog
le, 4-22
Intrinsic, 4-22
CATOPEN
Intrinsic, 4-23
Open application message catalog, 4-23
CATREAD
Access message facility and output messages,
4-25
Intrinsic, 4-25
CAUSEBREAK
Intrinsic, 4-28
Place a session in break mode, 4-28
Cause return from interrupt procedure
FINTEXIT, 4-168
Change DB register pointer
SWITCHDB, 4-606
Change length of USL le
EXPANDUSLF, 4-66
Change priority of process
GETPRIORITY, 4-280
Character Handling
NLFINDSTR, 4-500
NLJUDGE, 4-526
NLSUBSTR, 4-542
Characters of string, replace nondisplayable
NLREPCHAR, 4-537
Character string, print on listing device
PRINT, 4-553
Character string, print on system console
PRINTOP, 4-555
Character string, print on system console/reply
PRINTOPREPLY, 4-557
Character strings, compare
NLCOLLATE, 4-489
NLCOLLATE2, 4-491
Character strings, scan and move
NLSCANMOVE, 4-539
Child of calling process
CREATE, 4-36
Child process, delete
KILL, 4-459
Child process, return PIN
GETPROCID, 4-283
Child process, return status
GETPROCINFO, 4-284
CLEANUSL
Delete inactive entries from USL le, 4-29
Intrinsic, 4-29
CLOCK
Intrinsic, 4-31
Return system time, 4-31
Close access to user logging facility
CLOSELOG, 4-32
Close a le
FCLOSE, 4-79
CLOSELOG
Close access to user logging facility, 4-32
Intrinsic, 4-32
Close scratch le and restore data stack
SORTEND, 4-585
Close specied application message catalog le
CATCLOSE, 4-22
CM from NM, mixed-mode execution
HPSWITCHTOCM, 4-417
CM plabel, get for switch to CM
HPLOADCMPROCEDURE, 4-371
Code, condition, 2-8
Coding procedures
Intrinsic, 1-3
Collectively enables/disables arithmetic traps
ARITRAP, 4-12
COMMAND
Execute command programmatically, 4-34
Intrinsic, 4-34
Command, execute programmatically
HPCICOMMAND, 4-298
Command image, parse user dened
MYCOMMAND, 4-484
Command, programmatic execution
COMMAND, 4-34
Compare language dependent character strings
NLCOLLATE, 4-489
NLCOLLATE2, 4-491
Compare strings of dierent length
NLKEYCOMPARE, 4-528
Compare string to pattern from NLMATCHINIT
NLMATCH, 4-531
Compatibility mode SL procedure, unload
UNLOADPROC, 4-609
Compatibility mode stack, alter DB to Z area
ZSIZE, 4-628
Compatibility mode stack, expand/contract
DLSIZE, 4-56
Compile pattern into NLMATCH form
NLMATCHINIT, 4-532
Concatenate le name and language number
NLAPPEND, 4-488
Condition code, 2-8
Condition code, set for calling process
HPSETCCODE, 4-399
Contract/expand compatibility mode stack
DLSIZE, 4-56
Control access mode of les/devices
FSETMODE, 4-247
Control device
HPDEVCONTROL, 4-310
Control operation, on a le or device
FCONTROL, 4-84
Control operations for a printer
FDEVICECONTROL, 4-108
Control operations for a spooled device le
FDEVICECONTROL, 4-108
CONTROL-Y signal, accept another
RESETCONTROL, 4-576
Conversion, 16-bit binary to numeric ASCII
string
ASCII, 4-15
Conversion and format information, return
NLNUMSPEC, 4-535
Convert 16-bit binary to numeric ASCII string
ASCII, 4-15
Convert 32-bit binary number to ASCII string
DASCII, 4-50
Convert ASCII string number to 32-bit binary
DBINARY, 4-53
Convert character string, phonetic to screen
NLSWITCHBUF, 4-545
Index-3
Convert character string, screen to phonetic
NLSWITCHBUF, 4-545
Convert data between binary oating-point
formats
HPFPCONVERT, 4-364
Convert date from character string to numeric
NLCONVCUSTDATE, 4-495
Convert native language numbers
NLCONVNUM, 4-497
Convert number from ASCII string to 16-bit
binary
BINARY, 4-19
Convert string from ASCII to EBCDIC
CTRANSLATE, 4-48
Convert string from EBCDIC to ASCII
CTRANSLATE, 4-48
Convert string from EBCDIK to JIS
CTRANSLATE, 4-48
Convert string from JIS to EBCDIK
CTRANSLATE, 4-48
Convert string to specied native format
NLFMTNUM, 4-512
Convert time format, character string to numeric
NLCONVCLOCK, 4-493
Copy data area to extra data segment
DMOVOUT, 4-61
Copy data from extra data segment
DMOVIN, 4-58
CPU time, return for process
PROCTIME, 4-565
CREATE
Create a process, 4-36
Intrinsic, 4-36
Create a process
CREATE, 4-36
Create extra data segment
GETDSEG, 4-272
Create le on shareable device
HPFOPEN, 4-331
CREATEPROCESS
Create process and assign system-dened les,
4-43
Intrinsic, 4-43
Create process and assign system-dened les
CREATEPROCESS, 4-43
Creates pipe le type object
HPPIPE, 4-392
CTRANSLATE
Convert string from ASCII to EBCDIC, 4-48
Convert string from EBCDIC to ASCII, 4-48
Convert string from EBCDIK to JIS, 4-48
Convert string from JIS to EBCDIK, 4-48
Intrinsic, 4-48
Current date and time returned
DATELINE, 4-52
Index-4
Current record, mark
FREMOVE, 4-243
Current VUF, return
HP32208, 4-287
D
DASCII
Convert 32-bit binary number to ASCII string,
4-50
Intrinsic, 4-50
Data alignment, 1-3
Data area, copy to extra data segment
DMOVOUT, 4-61
Data conversion, binary oating-point formats
HPFPCONVERT, 4-364
Data reference, 1-3
Data segment, alter size
ALTDSEG, 4-10
Data segment, copy data from
DMOVIN, 4-58
Data segment, create extra
GETDSEG, 4-272
Data segment management (DS)
Capability, 2-14
Data segment, release extra
FREEDSEG, 4-238
Data stack, read from direct access disk le
FREADDIR, 4-232
Data stack, restore and close scratch le
SORTEND, 4-585
Data stack, restore and end merging
MERGEEND, 4-474
Data type conversion, 1-3
Data types
Mapping, 2-5
Date and time, return
DATELINE, 4-52
Date, convert from character string to numeric
NLCONVCUSTDATE, 4-495
Date, format
FMTDATE, 4-187
Date, format calendar
FMTCALENDAR, 4-185
Date, format numeric as character string
NLFMTCUSTDATE, 4-506
Date, format through language dependent
template
NLFMTCALENDAR, 4-502
NLFMTDATE, 4-508
Date, format through long calendar format
NLFMTLONGCAL, 4-510
Date information returned, numeric
ALMANAC, 4-8
DATELINE
Intrinsic, 4-52
Return current date and time, 4-52
Date, return calendar
CALENDAR, 4-21
Day, format time
FMTCLOCK, 4-186
DBINARY
Convert ASCII string number to 32-bit binary,
4-53
Intrinsic, 4-53
Deactivate a relative I/O record
FDELETE, 4-107
DEBUG
Intrinsic, 4-55
Invoke debug facility, 4-55
Debug commands, execute dened system
HPDEBUG, 4-308
Debug facility, invoke
DEBUG, 4-55
Declaration
Intrinsics, 2-1
System intrinsics, 2-1
Decrease length of USL le
EXPANDUSLF, 4-66
Default parameters, 1-3
Dene
Itemnum and item pair options, 2-4
Dene le and establish access
FOPEN, 4-189
Dene parameter bit setting, 2-2
Delete calling process
TERMINATE, 4-607
Delete child process
KILL, 4-459
Delete entry from session-level variable table
HPCIDELETEVAR, 4-300
Delete inactive entries from USL le
CLEANUSL, 4-29
Description
Functional return, 2-7
Determine Byte Size of Character
NLJUDGE, 4-526
Determine if le pair is inactive/duplicative
FRELATE, 4-241
Determine process PIN that locked local RIN
LOCRINOWNER, 4-466
Device control
HPDEVCONTROL, 4-310
Device, perform control operation
FCONTROL, 4-84
Devices/les, control access mode
FSETMODE, 4-247
Direct access disk le, read logical record
FREADDIR, 4-232
Disable abort stack analysis facility
RESETDUMP, 4-577
Disable arithmetic trap
ARITRAP, 4-12
Disable arithmetic traps
HPENBLTRAP, 4-316
Disable/enable software interrupts
FINTSTATE, 4-169
Disarm/arm arithmetic trap handling procedure
XARITRAP, 4-617
Disarm/arm software library trap handling
procedure
XLIBTRAP, 4-624
Disarm/arm subsystem break trap handling
procedure
XCONTRAP, 4-622
Disarm/arm system trap handling procedure
XSYSTRAP, 4-626
Disarm system debugger from process abort
HPRESETDUMP, 4-394
Disk le le label information returned
FLABELINFO, 4-171
disk le, move record pointer
FSPACE, 4-250
disk le record, move to buer
FREADSEEK, 4-236
disk le, remove
FRENAME, 4-244
disk le, set logical record pointer
FPOINT, 4-221
disk le, update logical record
FUPDATE, 4-253
Display system catalog error message
HPERRMSG, 4-321
DLSIZE
Expand/Contract compatibility mode stack,
4-56
Intrinsic, 4-56
DMOVIN
Copy data from extra data segment, 4-58
Intrinsic, 4-58
DMOVOUT
Copy data area to extra data segment, 4-61
Intrinsic, 4-61
duplicate le descriptor
HPFDUPLICATE, 4-327
duplicate handle
HPFDUPLICATE, 4-327
Duplicative/inactive, determine le pair
FRELATE, 4-241
Dynamically enter privileged mode
GETPRIVMODE, 4-282
Dynamically load native mode library procedure
HPGETPROCPLABEL, 4-368
Dynamically return program to nonprivileged
mode
GETUSERMODE, 4-286
Index-5
Dynamically unload compatibility mode SL
procedure
UNLOADPROC, 4-609
Dynamically unlock le
FUNLOCK, 4-252
E
EBCDIC string conversion to ASCII
CTRANSLATE, 4-48
EBCDIC, translate string from/to
NLTRANSLATE, 4-548
EBCDIK string conversion to JIS
CTRANSLATE, 4-48
Enable arithmetic trap
ARITRAP, 4-12
Enable/disable software interrupts
FINTSTATE, 4-169
Enables arithmetic traps
HPENBLTRAP, 4-316
ENDLOG
Intrinsic, 4-64
Mark end of user logging transaction, 4-64
End merge and release work area
HPMERGEEND, 4-375
End merging and restore data stack
MERGEEND, 4-474
End sort operation, release work area
HPSORTEND, 4-403
Enter privileged mode, dynamically
GETPRIVMODE, 4-282
Entries, clean inactive from USL le
CLEANUSL, 4-29
Entry, delete from variable table
HPCIDELETEVAR, 4-300
Entry, search array for specied
SEARCH, 4-578
Error
Abort, 2-12
Condition codes, 2-8
Status parameter, 2-9
Error information for le I/O errors, return
FCHECK, 4-69
Error message, get/display for system catalog
HPERRMSG, 4-321
Error message, retrieve if fatal
HPMERGEERRORMESS, 4-376
HPSORTERRORMESS, 4-405
Error, read from process stack
HPERRREAD, 4-325
Error stack, return depth of process
HPERRDEPTH, 4-319
Establish access for le on device
HPFOPEN, 4-331
Exception condition
le, 4-395
Index-6
Exclusive use, lock le
FLOCK, 4-182
Execute command programmatically
COMMAND, 4-34
HPCICOMMAND, 4-298
Execute dened system debug commands
HPDEBUG, 4-308
Execute full stack trace
STACKDUMP, 4-597
Execution errors, 2-8
Execution of NM to CM, mixed-mode
HPSWITCHTOCM, 4-417
Execution privileges, 1-1
Expand/contract compatibility mode stack
DLSIZE, 4-56
EXPANDUSLF
Change length of USL le, 4-66
Intrinsic, 4-66
Extensibility without source code changes, 1-3
External declarations
Data checking, 1-3
External routines, 1-3
Extract Bytes
NLSUBSTR, 4-542
Extra data segment, copy data from
DMOVIN, 4-58
Extra data segment, copy from data area
DMOVOUT, 4-61
Extra data segment, create
GETDSEG, 4-272
Extra data segment, release
FREEDSEG, 4-238
F
Facility access, close user logging
CLOSELOG, 4-32
Fatal error message, retrieve
HPMERGEERRORMESS, 4-376
HPSORTERRORMESS, 4-405
Fatal error, retrieve and print message
SORTERRORMESS, 4-586
Fatal error, retrieve message
MERGEERRORMESS, 4-475
FATHER
Intrinsic, 4-68
Request PIN of parent process, 4-68
FCHECK
Intrinsic, 4-69
Return error information for le I/O errors,
4-69
FCHECK error number returned
FERRMSG, 4-130
FCLOSE
Close a le, 4-79
Intrinsic, 4-79
FCONTROL
Intrinsic, 4-84
Perform control operation on a le or device,
4-84
FDELETE
Deactivate a relative I/O record, 4-107
Intrinsic, 4-107
FDEVICECONTROL
Control operations for printer or spooled
device le, 4-108
Intrinsic, 4-108
FERRMSG
Intrinsic, 4-130
Returns message corresponding to FCHECK
error number, 4-130
FFILEINFO
Intrinsic, 4-131
Returns information about a le, 4-131
FFINDBYKEY
Intrinsic, 4-151
Position record pointer, 4-151
FFINDN
Intrinsic, 4-153
Position record pointer, 4-153
FGETINFO
Intrinsic, 4-155
Return access and status information for le,
4-155
FGETKEYINFO
Intrinsic, 4-164
Request KSAM access information, 4-164
Request KSAM status information, 4-164
Status information for KSAM le, 4-164
File access
FOPEN, 4-189
File access, terminate
FCLOSE, 4-79
File, create on shareable device
HPFOPEN, 4-331
File designator, parse and validate
FPARSE, 4-218
File display, print on list device
PRINTFILEINFO, 4-554
File has exception condition
HPSELECT, 4-395
File information returned
FFILEINFO, 4-131
File information returned, access
FGETINFO, 4-155
File information returned, status
FGETINFO, 4-155
File I/O errors, error information returned
FCHECK, 4-69
File label information, disk le returned
FLABELINFO, 4-171
File label, read
FREADLABEL, 4-234
File, lock for exclusive use
FLOCK, 4-182
File name, concatenate
NLAPPEND, 4-488
File name of rst library, return
HPFIRSTLIBRARY, 4-329
File pair, determine if inactive/duplicative
FRELATE, 4-241
File, perform control operation
FCONTROL, 4-84
File, read logical record to stack
FREAD, 4-223
File ready to perform read
HPSELECT, 4-395
File ready to perform write
HPSELECT, 4-395
Files/devices, control access mode
FSETMODE, 4-247
File, unlock dynamically
FUNLOCK, 4-252
FINDJCW
Intrinsic, 4-166
Search JCW table and return value, 4-166
FINTEXIT
Cause return from interrupt procedure, 4-168
Intrinsic, 4-168
FINTSTATE
Enable/disable software interrupts, 4-169
Intrinsic, 4-169
FLABELINFO
Intrinsic, 4-171
Return information from le label, disk le,
4-171
Floating-point formats, convert binary
HPFPCONVERT, 4-364
FLOCK
Intrinsic, 4-182
Lock le for exclusive use, 4-182
Flush contents, User Logging memory buer
FLUSHLOG, 4-184
FLUSHLOG
Flush contents, User Logging memory buer,
4-184
Intrinsic, 4-184
FMTCALENDAR
Format calendar date, 4-185
Intrinsic, 4-185
FMTCLOCK
Format time of day, 4-186
Intrinsic, 4-186
FMTDATE
Format calendar date and time of day, 4-187
Intrinsic, 4-187
Index-7
FOPEN
Dene le and establish access, 4-189
Intrinsic, 4-189
Format
Intrinsic syntax, 2-3
Format and conversion information, return
NLNUMSPEC, 4-535
Format calendar date
FMTCALENDAR, 4-185
Format calendar date and time of day
FMTDATE, 4-187
Format date through language dependent
template
NLFMTCALENDAR, 4-502
Format date through long calendar format
NLFMTLONGCAL, 4-510
Format date/time through language dependent
template
NLFMTDATE, 4-508
Format numeric date as character string
NLFMTCUSTDATE, 4-506
Format numeric time as character string
NLFMTCLOCK, 4-504
Format time of day
FMTCLOCK, 4-186
FPARSE
Intrinsic, 4-218
Parse and validate le designator, 4-218
FPOINT
Intrinsic, 4-221
Set logical record pointer for disk le, 4-221
FREAD
Intrinsic, 4-223
Read logical record from le to stack, 4-223
FREADBACKWARD
Intrinsic, 4-226
Read reverse capability, 4-226
FREADBYKEY
Intrinsic, 4-228
Logical record, read randomly, 4-228
Read logical record randomly to data stack,
4-228
FREADC
Intrinsic, 4-230
Logical record, read chronologically, 4-230
Read logical record chronologically to data
stack, 4-230
FREADDIR
Intrinsic, 4-232
Read logical record from direct access disk
le, 4-232
FREADLABEL
Intrinsic, 4-234
Read user le label, 4-234
FREADSEEK
Index-8
Intrinsic, 4-236
Move record from disk le to buer, 4-236
FREEDSEG
Intrinsic, 4-238
Release extra data segment, 4-238
Free local RINs from allocation to job
FREELOCRIN, 4-240
FREELOCRIN
Free local RINs from allocation to job, 4-240
Intrinsic, 4-240
FRELATE
Determine if le pair is inactive/duplicative,
4-241
Intrinsic, 4-241
FREMOVE
Current record, mark, 4-243
Intrinsic, 4-243
Mark current record, KSAM le, 4-243
FRENAME
Intrinsic, 4-244
Remove disk le, 4-244
FSETMODE
Control access modes of les/devices, 4-247
Intrinsic, 4-247
FSPACE
Intrinsic, 4-250
Move record pointer on tape/disk le, 4-250
Full stack trace, execute
STACKDUMP, 4-597
Functional return description, 2-7
Functional returns, intrinsic, 1-1
FUNLOCK
Dynamically unlock le, 4-252
Intrinsic, 4-252
FUPDATE
Intrinsic, 4-253
Update logical record in disk le, 4-253
FWRITE
Intrinsic, 4-255
Write logical/physical record from stack to
le, 4-255
FWRITEDIR
Intrinsic, 4-263
Write logical record from stack to disk le,
4-263
FWRITELABEL
Intrinsic, 4-265
Write user le label, 4-265
G
GENMESSAGE
Access message catalogs, 4-267
Intrinsic, 4-267
Get CM plabel for switch to CM
HPLOADCMPROCEDURE, 4-371
GETDSEG
Create extra data segment, 4-272
Intrinsic, 4-272
GETINFO
Intrinsic, 4-275
Return user-supplied information, 4-275
GETJCW
Intrinsic, 4-277
Return system dened JCW value, 4-277
GETLOCRIN
acquire local RINs, 4-278
Intrinsic, 4-278
GETORIGIN
Intrinsic, 4-279
Return source of activation call for process,
4-279
GETPRIORITY
Change priority of process, 4-280
Intrinsic, 4-280
GETPRIVMODE
Dynamically enter privileged mode, 4-282
Intrinsic, 4-282
GETPROCID
Intrinsic, 4-283
Return PIN of child process, 4-283
GETPROCINFO
Intrinsic, 4-284
Return status for parent/child process, 4-284
Get session-level variable value/attribute
HPCIGETVAR, 4-301
Get system catalog error message
HPERRMSG, 4-321
GETUSERMODE
Dynamically return program to nonprivileged
mode, 4-286
Intrinsic, 4-286
H
HP32208
Current VUF, return, 4-287
Intrinsic, 4-287
Return current VUF, 4-287
HPACDINFO
Intrinsic, 4-288
List security information from ACD, 4-288
HPACDPUT
Intrinsic, 4-294
Manipulate security information in ACD,
4-294
HPCICOMMAND
Execute command programmatically, 4-298
Intrinsic, 4-298
HPCIDELETEVAR
Intrinsic, 4-300
Remove entry from session-level variable table,
4-300
HPCIGETVAR
Get session-level variable value/attribute,
4-301
Intrinsic, 4-301
HPCIPUTVAR
Intrinsic, 4-305
Set value of session-level variable, 4-305
HPDEBUG
Execute dened system debug commands,
4-308
Intrinsic, 4-308
HPDEVCONTROL
Control device, 4-310
Intrinsic, 4-310
HPDEVCREATE
Creates fo le, 4-312
Creates link les, 4-312
Creates streams le, 4-312
Intrinsics, 4-312
HPENBLTRAP
Enables/disables arithmetic traps, 4-316
Intrinsic, 4-316
HPERRDEPTH
Intrinsic, 4-319
Return depth of process error stack, 4-319
HPERRMSG
Get or display system catalog error message,
4-321
Intrinsic, 4-321
HPERRREAD
Intrinsic, 4-325
Read error from process stack, 4-325
HPFDUPLICATE
duplicate le descriptor, 4-327
duplicate handle, 4-327
intrinsic, 4-327
share data pointer, 4-327
HPFIRSTLIBRARY
Intrinsic, 4-329
Return le name of rst library, 4-329
HPFOPEN
Create le on shareable device, 4-331
Establish access for le on device, 4-331
Intrinsic, 4-331
HPFPCONVERT
Convert data between binary oating-point
format, 4-364
Intrinsic, 4-364
HPGETPROCPLABEL
Dynamically load native mode library
procedure, 4-368
Intrinsic, 4-368
HPLOADCMPROCEDURE
Index-9
Get CM plabel for switch to CM, 4-371
Intrinsic, 4-371
HPLOADNMPROC
Intrinsic, 4-373
Return plabel, NM procedure, 4-373
HPMERGEEND
Intrinsic, 4-375
Release work area and end merge, 4-375
HPMERGEERRORMESS
Intrinsic, 4-376
Retrieve error message if fatal, 4-376
HPMERGEINIT
Initialize MERGE subsystem, 4-378
Intrinsic, 4-378
HPMERGEOUTPUT
Intrinsic, 4-383
Retrieve records from MERGE, 4-383
HPMERGESTAT
Intrinsic, 4-384
Print MERGE statistics on $STDLIST, 4-384
HPMERGETITLE
Intrinsic, 4-386
Print version and title on $STDLIST, 4-386
HPMYFILE
Intrinsic, 4-387
Return program le name that called intrinsic,
4-387
HPMYPROGRAM
Intrinsic, 4-389
Return program le name being executed,
4-389
HPPIPE
Creates pipe le type object, 4-392
Intrinsic, 4-392
HPRESETDUMP
Disarm system debugger from process abort,
4-394
Intrinsic, 4-394
HPSELECT
le has exception condition, 4-395
le ready to perform read, 4-395
le ready to perform write, 4-395
Intrinsic, 4-395
HPSETCCODE
Intrinsic, 4-399
Set condition code for calling process, 4-399
HPSETDUMP
Arm system debugger call from process abort,
4-401
Intrinsic, 4-401
HPSORTEND
Intrinsic, 4-403
Release SOT work area and end sort operation,
4-403
HPSORTERRORMESS
Index-10
Intrinsic, 4-405
Retrieve error message if fatal error, 4-405
HPSORTINIT
Initialize the SORT subsystem, 4-406
Intrinsic, 4-406
HPSORTINPUT
Intrinsic, 4-411
Pass records to SORT, 4-411
HPSORTOUTPUT
Intrinsic, 4-412
Retrieve record from SORT, 4-412
HPSORTSTAT
Intrinsic, 4-414
Print SORT statistics on $STDLIST, 4-414
HPSORTTITLE
Intrinsic, 4-416
Print version and title for SORT on $STDLIST,
4-416
HPSWITCHTOCM
Intrinsic, 4-417
Mixed-mode execution for NM to CM, 4-417
HPSWTONMNAME
Intrinsic, 4-419
Invoke NM procedure, 4-419
HPSWTONMPLABEL
Intrinsic, 4-421
Invoke NM procedure, 4-421
HPUNLOADCMPROCEDURE
Intrinsic, 4-423
Unload target procedure, 4-423
HPVOLINFO
Intrinsic, 4-425
Return volume information, 4-425
I
Implementation
Mapping data types, 2-5
Implementing intrinsics, 2-1
Inactive/duplicative, determine le pair
FRELATE, 4-241
Inactive entries, clean from USL le
CLEANUSL, 4-29
Increase length of USL le
EXPANDUSLF, 4-66
Information about open User Logging le
LOGINFO, 4-468
LOGSTATUS, 4-470
Information, return user-supplied
GETINFO, 4-275
Initialize MERGE subsystem
HPMERGEINIT, 4-378
MERGEINIT, 4-476
Initialize the SORT subsystem
HPSORTINIT, 4-406
Initialize USL le to empty state
INITUSLF, 4-446
Initiate completion for I/O request
IODONTWAIT, 4-448
IOWAIT, 4-450
Initiate session on specied terminal
STARTSESS, 4-599
Initiate SORT program
SORTINIT, 4-587
INITUSLF
Initialize USL le to empty state, 4-446
Intrinsic, 4-446
Interface
Intrinsic, 1-3
Inter-Language calls, 1-3
Interrupt procedure, cause return from
FINTEXIT, 4-168
Interrupts, enable/disable software
FINTSTATE, 4-169
intrinsic
HPFDUPLICATE, 4-327
Intrinsic
ABORTSESS, 4-2
ACTIVATE, 4-4
ADJUSTUSLF, 4-6
ALMANAC, 4-8
ALTDSEG, 4-10
ARITRAP, 4-12
ASCII, 4-15
BEGINLOG, 4-17
BINARY, 4-19
CALENDAR, 4-21
Call errors, 2-8
Calling, 2-1
Calls, 2-1
Capability, 2-13
CATCLOSE, 4-22
CATOPEN, 4-23
CATREAD, 4-25
CAUSEBREAK, 4-28
CLEANUSL, 4-29
CLOCK, 4-31
CLOSELOG, 4-32
Coding procedures, 1-3
COMMAND, 4-34
CREATE, 4-36
CREATEPROCESS, 4-43
CTRANSLATE, 4-48
DASCII, 4-50
Data type conversion, 1-3
DATELINE, 4-52
DBINARY, 4-53
DEBUG, 4-55
Declarations, 2-1
DLSIZE, 4-56
DMOVIN, 4-58
DMOVOUT, 4-61
ENDLOG, 4-64
EXPANDUSLF, 4-66
FATHER, 4-68
FCHECK, 4-69
FCLOSE, 4-79
FCONTROL, 4-84
FDELETE, 4-107
FDEVICECONTROL, 4-108
FERRMSG, 4-130
FFILEINFO, 4-131
FFINDBYKEY, 4-151
FFINDN, 4-153
FGETINFO, 4-155
FGETKEYINFO, 4-164
FINDJCW, 4-166
FINTEXIT, 4-168
FINTSTATE, 4-169
FLABELINFO, 4-171
FLOCK, 4-182
FLUSHLOG, 4-184
FMTCALENDAR, 4-185
FMTCLOCK, 4-186
FMTDATE, 4-187
FOPEN, 4-189
FPARSE, 4-218
FPOINT, 4-221
FREAD, 4-223
FREADBACKWARD, 4-226
FREADBYKEY, 4-228
FREADC, 4-230
FREADDIR, 4-232
FREADLABEL, 4-234
FREADSEEK, 4-236
FREEDSEG, 4-238
FREELOCRIN, 4-240
FRELATE, 4-241
FREMOVE, 4-243
FRENAME, 4-244
FSETMODE, 4-247
FSPACE, 4-250
Functional returns, 1-1
FUNLOCK, 4-252
FUPDATE, 4-253
FWRITE, 4-255
FWRITEDIR, 4-263
FWRITELABEL, 4-265
GENMESSAGE, 4-267
GETDSEG, 4-272
GETINFO, 4-275
GETJCW, 4-277
GETLOCRIN, 4-278
GETORIGIN, 4-279
GETPRIORITY, 4-280
GETPRIVMODE, 4-282
Index-11
GETPROCID, 4-283
GETPROCINFO, 4-284
GETUSERMODE, 4-286
HP32208, 4-287
HPACDINFO, 4-288
HPACDPUT, 4-294
HPCICOMMAND, 4-298
HPCIDELETEVAR, 4-300
HPCIGETVAR, 4-301
HPCIPUTVAR, 4-305
HPDEBUG, 4-308
HPDEVCONTROL, 4-310
HPDEVCREATE, 4-312
HPENBLTRAP, 4-316
HPERRDEPTH, 4-319
HPERRMSG, 4-321
HPERRREAD, 4-325
HPFIRSTLIBRARY, 4-329
HPFOPEN, 4-331
HPFPCONVERT, 4-364
HPGETPROCPLABEL, 4-368
HPLOADCMPROCEDURE, 4-371
HPLOADNMPROC, 4-373
HPMERGEEND, 4-375
HPMERGEERRORMESS, 4-376
HPMERGEINIT, 4-378
HPMERGEOUTPUT, 4-383
HPMERGESTAT, 4-384
HPMERGETITLE, 4-386
HPMYFILE, 4-387
HPMYPROGRAM, 4-389
HPPIPE, 4-392
HPRESETDUMP, 4-394
HPSELECT, 4-395
HPSETCCODE, 4-399
HPSETDUMP, 4-401
HPSORTEND, 4-403
HPSORTERRORMESS, 4-405
HPSORTINIT, 4-406
HPSORTINPUT, 4-411
HPSORTOUTPUT, 4-412
HPSORTSTAT, 4-414
HPSORTTITLE, 4-416
HPSWITCHTOCM, 4-417
HPSWTONMNAME, 4-419
HPSWTONMPLABEL, 4-421
HPUNLOADCMPROCEDURE, 4-423
HPVOLINFO, 4-425
Implementation, 2-1
INITUSLF, 4-446
Interface, 1-3
IODONTWAIT, 4-448
IOWAIT, 4-450
JOBINFO, 4-452
KILL, 4-459
Index-12
LOADPROC, 4-460
LOCKGLORIN, 4-462
LOCKLOCRIN, 4-464
LOCRINOWNER, 4-466
LOGINFO, 4-468
LOGSTATUS, 4-470
MAIL, 4-472
Mechanism, 1-3
MERGEEND, 4-474
MERGEERRORMESS, 4-475
MERGEINIT, 4-476
MERGEOUTPUT, 4-481
MERGESTAT, 4-482
MERGETITLE, 4-483
Mnemonic, 2-3
MYCOMMAND, 4-484
NLAPPEND, 4-488
NLCOLLATE, 4-489
NLCOLLATE2, 4-491
NLCONVCLOCK, 4-493
NLCONVCUSTDATE, 4-495
NLCONVNUM, 4-497
NLFINDSTR, 4-500
NLFMTCALENDAR, 4-502
NLFMTCLOCK, 4-504
NLFMTCUSTDATE, 4-506
NLFMTDATE, 4-508
NLFMTLONGCAL, 4-510
NLFMTNUM, 4-512
NLGETLANG, 4-516
NLINFO, 4-518
NLJUDGE, 4-526
NLKEYCOMPARE, 4-528
NLMATCH, 4-531
NLMATCHINIT, 4-532
NLNUMSPEC, 4-535
NLREPCHAR, 4-537
NLSCANMOVE, 4-539
NLSUBSTR, 4-542
NLSWITCHBUF, 4-545
NLTRANSLATE, 4-548
OPENLOG, 4-550
Parameters, 1-1
PAUSE, 4-552
PRINT, 4-553
PRINTFILEINFO, 4-554
PRINTOP, 4-555
PRINTOPREPLY, 4-557
Procedure body, 1-1
Procedure header, 1-1
PROCINFO, 4-559
PROCTIME, 4-565
PUTJCW, 4-566
QUIT, 4-568
QUITPROG, 4-569
READ, 4-570
READX, 4-572
RECEIVEMAIL, 4-574
RESETCONTROL, 4-576
RESETDUMP, 4-577
SEARCH, 4-578
SENDMAIL, 4-580
SETDUMP, 4-582
SETJCW, 4-584
SORTEND, 4-585
SORTERRORMESS, 4-586
SORTINIT, 4-587
SORTINPUT, 4-592
SORTOUTPUT, 4-593
SORTSTAT, 4-595
SORTTITLE, 4-596
STACKDUMP, 4-597
STARTSESS, 4-599
SUSPEND, 4-604
SWITCHDB, 4-606
TERMINATE, 4-607
TIMER, 4-608
UNLOADPROC, 4-609
UNLOCKGLORIN, 4-610
UNLOCKLOCRIN, 4-611
Using, 2-1
WHO, 4-612
WRITELOG, 4-615
XARITRAP, 4-617
XCONTRAP, 4-622
XLIBTRAP, 4-624
XSYSTRAP, 4-626
ZSIZE, 4-628
Intrinsic call description
Syntax, 2-3
Intrinsic mechanism, 1-3
Intrinsic trap, 2-12
Invoke debug facility
DEBUG, 4-55
Invoke intrinsics, 2-1
Invoke NM procedure
HPSWTONMNAME, 4-419
HPSWTONMPLABEL, 4-421
Invoke routines
Intrinsic mechanism, 1-3
IODONTWAIT
Initiate completion for I/O request, 4-448
Intrinsic, 4-448
I/O record, deactivate
FDELETE, 4-107
I/O request, initiate completion for
IODONTWAIT, 4-448
IOWAIT, 4-450
IOWAIT
Initiate completion for I/O request, 4-450
Intrinsic, 4-450
Itemnum and item pairs
dene options, 2-4
J
JCW, set bits in stream
SETJCW, 4-584
JCW table search, return value
FINDJCW, 4-166
JCW value, assign to JCW table
PUTJCW, 4-566
JCW value, return system dened
GETJCW, 4-277
JIS string conversion to EBCDIK
CTRANSLATE, 4-48
JOBINFO
Access job and session information, 4-452
Intrinsic, 4-452
Job information, access
JOBINFO, 4-452
K
KILL
Delete child process, 4-459
Intrinsic, 4-459
L
Label, write user le
FWRITELABEL, 4-265
Language dependent character strings, compare
NLCOLLATE, 4-489
NLCOLLATE2, 4-491
Language dependent information, return
NLINFO, 4-518
Language ID, return current
NLGETLANG, 4-516
Language number, concatenate
NLAPPEND, 4-488
Library, return le name of rst
HPFIRSTLIBRARY, 4-329
List security information from ACD
HPACDINFO, 4-288
Load compatibility mode SL procedure
LOADPROC, 4-460
Load native mode library procedure
HPGETPROCPLABEL, 4-368
LOADPROC
Intrinsic, 4-460
Load compatibility mode SL procedure, 4-460
Local RINs, acquire
GETLOCRIN, 4-278
Local RINs, free from allocation to job
FREELOCRIN, 4-240
Lock le for exclusive use
Index-13
FLOCK, 4-182
Lock global RIN
LOCKGLORIN, 4-462
LOCKGLORIN
Intrinsic, 4-462
Lock global RIN, 4-462
Lock local RIN
LOCKLOCRIN, 4-464
LOCKLOCRIN
Intrinsic, 4-464
Lock local RIN, 4-464
LOCRINOWNER
Determine process PIN that locked local RIN,
4-466
Intrinsic, 4-466
Logical record pointer for disk le, set
FPOINT, 4-221
Logical record, read chronologically
FREADC, 4-230
Logical record, read from current record pointer
FREADBACKWARD, 4-226
Logical record, read from le to stack
FREAD, 4-223
Logical record, read randomly
FREADBYKEY, 4-228
Logical record, update in disk le
FUPDATE, 4-253
Logical record, write from stack to disk le
FWRITEDIR, 4-263
Logical record, write from stack to le
FWRITE, 4-255
LOGINFO
Information about open User Logging le,
4-468
Intrinsic, 4-468
LOGSTATUS
Information about open User Logging le,
4-470
Intrinsic, 4-470
M
MAIL
Intrinsic, 4-472
Test mailbox status, 4-472
Mailbox status, test
MAIL, 4-472
Mail, send to another process
SENDMAIL, 4-580
Manage processes, 1-1
Manipulate security information in ACD
HPACDPUT, 4-294
Mapping
Data types, 2-5
Mark beginning of user logging transaction
BEGINLOG, 4-17
Index-14
Mark current record, KSAM le
FREMOVE, 4-243
Mark end of user logging transaction
ENDLOG, 4-64
Mechanism
Intrinsic, 1-3
Invoke routines, 1-3
Mechanism facilities, 2-1
Memory buer, ush contents
FLUSHLOG, 4-184
MERGEEND
Intrinsic, 4-474
Restore data stack and end merging, 4-474
MERGEERRORMESS
Intrinsic, 4-475
Retrieve message if fatal error, 4-475
MERGEINIT
Initialize MERGE subsystem, 4-476
Intrinsic, 4-476
MERGEOUTPUT
Intrinsic, 4-481
Specify record output from MERGE program,
4-481
MERGE program, specify output
MERGEOUTPUT, 4-481
MERGE, retrieve records from
HPMERGEOUTPUT, 4-383
MERGESTAT
Intrinsic, 4-482
Print MERGE statistics on $STDLIST, 4-482
MERGE statistics, print on $STDLIST
MERGESTAT, 4-482
MERGE subsystem, initialize
HPMERGEINIT, 4-378
MERGEINIT, 4-476
MERGETITLE
Intrinsic, 4-483
Print version number and title on $STDLIST,
4-483
Message catalog le, close
CATCLOSE, 4-22
Message catalog, open
CATOPEN, 4-23
Message catalogs, access
GENMESSAGE, 4-267
Message facility access and output messages
CATREAD, 4-25
Message, retrieve if fatal error
MERGEERRORMESS, 4-475
Message returned, corresponds to FCHECK
FERRMSG, 4-130
Mixed-mode execution for NM to CM
HPSWITCHTOCM, 4-417
Mnemonic
Intrinsic, 2-3
Mnemonic, meaning, 2-3
mode
Option Privileged, 2-3
Move and scan character strings
NLSCANMOVE, 4-539
Move record from disk le to buer
FREADSEEK, 4-236
Move record pointer on tape/disk le
FSPACE, 4-250
Multiple resource identication number (MR)
Capability, 2-14
MYCOMMAND
Intrinsic, 4-484
Parse user dened command image, 4-484
N
Name, search array for specied
SEARCH, 4-578
Name translation
Case-insensitive languages, 1-3
Native mode library procedure, load
HPGETPROCPLABEL, 4-368
NLAPPEND
Concatenate le name and language number,
4-488
Intrinsic, 4-488
NLCOLLATE
Compare language dependent character strings,
4-489
Intrinsic, 4-489
NLCOLLATE2
Compare language dependent character strings
from a COBOL program, 4-491
Intrinsic, 4-491
NLCONVCLOCK
Convert time format, character string to
numeric, 4-493
Intrinsic, 4-493
NLCONVCUSTDATE
Convert date from character string to numeric,
4-495
Intrinsic, 4-495
NLCONVNUM
Convert native language numbers, 4-497
Intrinsic, 4-497
NLFINDSTR
Intrinsic, 4-500
NLFMTCALENDAR
Format date through language dependent
template, 4-502
Intrinsic, 4-502
NLFMTCLOCK
Format numeric time as character string,
4-504
Intrinsic, 4-504
NLFMTCUSTDATE
Format numeric date as character string,
4-506
Intrinsic, 4-506
NLFMTDATE
Format date/time through language dependent
template, 4-508
Intrinsic, 4-508
NLFMTLONGCAL
Format date through long calendar format,
4-510
Intrinsic, 4-510
NLFMTNUM
Convert string to specied native format,
4-512
Intrinsic, 4-512
NLGETLANG
Intrinsic, 4-516
Return current language ID, 4-516
NLINFO
Intrinsic, 4-518
Return language dependent information, 4-518
NLJUDGE
Intrinsic, 4-526
NLKEYCOMPARE
Compare strings of dierent length, 4-528
Intrinsic, 4-528
NLMATCH
Compare string to pattern from
NLMATCHINIT, 4-531
Intrinsic, 4-531
NLMATCHINIT
Compile pattern into NLMATCH form, 4-532
Intrinsic, 4-532
NLNUMSPEC
Intrinsic, 4-535
Return format and conversion information,
4-535
NLREPCHAR
Intrinsic, 4-537
Replace nondisplayable characters of string,
4-537
NLSCANMOVE
Intrinsic, 4-539
Move and scan character strings, 4-539
NLSUBSTR
Intrinsic, 4-542
NLSWITCHBUF
Convert character string, phonetic to screen,
4-545
Convert character string, screen to phonetic,
4-545
Intrinsic, 4-545
NLTRANSLATE
Intrinsic, 4-548
Index-15
Translate string from/to EBCDIC, 4-548
NM to CM, mixed-mode execution
HPSWITCHTOCM, 4-417
NonPrivileged mode, return program
GETUSERMODE, 4-286
Nonshareable device (ND)
Capability, 2-14
Number, convert to native format
NLFMTNUM, 4-512
Numbers, convert native language
NLCONVNUM, 4-497
Numeric date information, returned
ALMANAC, 4-8
O
Open application message catalog
CATOPEN, 4-23
OPENLOG
Access to User Logging facility, 4-550
Intrinsic, 4-550
Open User Logging le, information
LOGINFO, 4-468
LOGSTATUS, 4-470
Option
Itemnum and item pairs, 2-4
Using parameter bit setting, 2-2
Option privileged, 2-3
Output messages and access message facility
CATREAD, 4-25
P
Parameter
Status error, 2-9
Parameter alignment, 2-2
Parameter bit setting, 2-2
Parameter checking, 1-3
Parameters, intrinsic, 1-1
Parent process, request PIN of
FATHER, 4-68
Parent process, return status
GETPROCINFO, 4-284
Parse and validate le designator
FPARSE, 4-218
Parse user dened command image
MYCOMMAND, 4-484
Pass records to SORT
HPSORTINPUT, 4-411
PAUSE
Intrinsic, 4-552
Suspend calling process for time specied,
4-552
Perform control operation on a le or device
FCONTROL, 4-84
Phonetic to screen, convert character string
NLSWITCHBUF, 4-545
Index-16
Physical record, write from stack to le
FWRITE, 4-255
PIN, return for child process
GETPROCID, 4-283
Place a session in break mode
CAUSEBREAK, 4-28
Position record pointer
FFINDBYKEY, 4-151
FFINDN, 4-153
Predene characteristics of le and access
FOPEN, 4-189
PRINT
Intrinsic, 4-553
Print character string on listing device, 4-553
Print character sting on system console
PRINTOP, 4-555
Print character string on listing device
PRINT, 4-553
Print character string on system console/reply
PRINTOPREPLY, 4-557
Printer, control operations
FDEVICECONTROL, 4-108
Print le display on list device
PRINTFILEINFO, 4-554
PRINTFILEINFO
Intrinsic, 4-554
Print le display on list device, 4-554
Print MERGE statistics on $STDLIST
HPMERGESTAT, 4-384
MERGESTAT, 4-482
PRINTOP
Intrinsic, 4-555
Print character string on system console,
4-555
PRINTOPREPLY
Intrinsic, 4-557
Print character string on system console/reply,
4-557
Print SORT program statistics on $STDLIST
SORTSTAT, 4-595
Print SORT statistics on $STDLIST
HPSORTSTAT, 4-414
Print version and title for SORT on $STDLIST
HPSORTTITLE, 4-416
Print version and title on $STDLIST
HPMERGETITLE, 4-386
Print version number and title on $STDLIST
MERGETITLE, 4-483
Print version number/title on $STDLIST
SORTTITLE, 4-596
Priority of process, change
GETPRIORITY, 4-280
Privileged mode (PM)
Capability, 2-3, 2-15
Privileged mode (PM), enter dynamically
GETPRIVMODE, 4-282
Procedure, arm/disarm system trap handling
XSYSTRAP, 4-626
Procedure, arm/disarm trap handling
XARITRAP, 4-617
XCONTRAP, 4-622
XLIBTRAP, 4-624
Procedure body
Intrinsic, 1-1
Procedure header
Intrinsic, 1-1
Procedure, invoke NM
HPSWTONMNAME, 4-419
HPSWTONMPLABEL, 4-421
Procedure, unload
HPUNLOADCMPROCEDURE, 4-423
Process abort, arm system debugger
SETDUMP, 4-582
Process abort, arm system debugger call from
HPSETDUMP, 4-401
Process abort, disarm system debugger
HPRESETDUMP, 4-394
Process, accept another CONTROL-Y signal
RESETCONTROL, 4-576
Process calling, abort
QUIT, 4-568
Process, change priority
GETPRIORITY, 4-280
Process creation
CREATE, 4-36
CREATEPROCESS, 4-43
Process, delete calling
TERMINATE, 4-607
Process error stack, return depth
HPERRDEPTH, 4-319
Processes, manage, 1-1
Process handling (PH)
Capability, 2-15
Process information, provide access
PROCINFO, 4-559
Process, receive mail from another
RECEIVEMAIL, 4-574
Process, request PIN of parent
FATHER, 4-68
Process, return CPU time
PROCTIME, 4-565
Process, return source of activation
GETORIGIN, 4-279
Process, send mail to another
SENDMAIL, 4-580
Process stack, read error
HPERRREAD, 4-325
Process structure, abort entire user
QUITPROG, 4-569
Process, suspend
SUSPEND, 4-604
Process, suspend for specied time
PAUSE, 4-552
PROCINFO
Access to process information, 4-559
Intrinsic, 4-559
PROCTIME
Intrinsic, 4-565
Return CPU time for process, 4-565
Program execution, capability check, 2-14
Programmatic execution of command
COMMAND, 4-34
HPCICOMMAND, 4-298
Programmatic sessions (PS)
Capability, 2-15
Programming languages
Mapping, 2-5
Program, return to nonprivileged mode
GETUSERMODE, 4-286
PUTJCW
Assign value of JCW in JCW table, 4-566
Intrinsic, 4-566
Q
QUIT
Abort calling process, 4-568
Intrinsic, 4-568
QUITPROG
Abort entire user process structure, 4-569
Intrinsic, 4-569
R
READ
Intrinsic, 4-570
Read $STDIN ASCII string into array, 4-570
Read error from process stack
HPERRREAD, 4-325
Read le
ready, 4-395
Read logical record chronologically to data stack
FREADC, 4-230
Read logical record from current record pointer
FREADBACKWARD, 4-226
Read logical record from direct access disk le
FREADDIR, 4-232
Read logical record from le to stack
FREAD, 4-223
Read logical record randomly to data stack
FREADBYKEY, 4-228
Read reverse capability
FREADBACKWARD, 4-226
Read $STDIN ASCII string into array
READ, 4-570
Read $STDINX ASCII string into array
READX, 4-572
Index-17
Read user le label
FREADLABEL, 4-234
READX
Intrinsic, 4-572
Read $STDINX ASCII string into array,
4-572
RECEIVEMAIL
Intrinsic, 4-574
Receive mail from another process, 4-574
Receive mail from another process
RECEIVEMAIL, 4-574
Record, move from disk le to buer
FREADSEEK, 4-236
Record output form MERGE program, specify
MERGEOUTPUT, 4-481
Record pointer, move on tape/disk le
FSPACE, 4-250
Record, retrieve from SORT
HPSORTOUTPUT, 4-412
Records, how output from SORT program
SORTOUTPUT, 4-593
Records, how supplied to SORT program
SORTINPUT, 4-592
Records, pass to SORT
HPSORTINPUT, 4-411
Records, retrieve from MERGE
HPMERGEOUTPUT, 4-383
Record, write to User Logging
WRITELOG, 4-615
Relative I/O record, deactivate
FDELETE, 4-107
Release extra data segment
FREEDSEG, 4-238
Release SORT work area and end sort operation
HPSORTEND, 4-403
Release work area and end merge
HPMERGEEND, 4-375
Remove disk le
FRENAME, 4-244
Replace nondisplayable characters of string
NLREPCHAR, 4-537
Request KSAM access information
FGETKEYINFO, 4-164
Request KSAM status information
FGETKEYINFO, 4-164
Request PIN of parent process
FATHER, 4-68
Request utility functions, 1-1
Required capabilities for intrinsic use, 2-13
RESETCONTROL
Accept another CONTROL-Y signal, 4-576
Intrinsic, 4-576
RESETDUMP
Disable abort stack analysis facility, 4-577
Intrinsic, 4-577
Index-18
Resources, system access, 1-1
Restore data stack and close scratch le
SORTEND, 4-585
Restore data stack and end merging
MERGEEND, 4-474
Retrieve and print message if fatal error
SORTERRORMESS, 4-586
Retrieve error message if fatal
HPMERGEERRORMESS, 4-376
Retrieve error message if fatal error
HPSORTERRORMESS, 4-405
Retrieve message if fatal error
MERGEERRORMESS, 4-475
Retrieve record from SORT
HPSORTOUTPUT, 4-412
Retrieve records from MERGE
HPMERGEOUTPUT, 4-383
Return access and status information for le
FGETINFO, 4-155
Return calendar date
CALENDAR, 4-21
Return CPU time for process
PROCTIME, 4-565
Return current date and time
DATELINE, 4-52
Return current language ID
NLGETLANG, 4-516
Return current VUF
HP32208, 4-287
Return depth of process error stack
HPERRDEPTH, 4-319
Return error information for le I/O errors
FCHECK, 4-69
Return le label information of disk le
FLABELINFO, 4-171
Return le name of rst library
HPFIRSTLIBRARY, 4-329
Return format and conversion information
NLNUMSPEC, 4-535
Return from interrupt procedure
FINTEXIT, 4-168
Return, Functional, 2-7
Return information about user
WHO, 4-612
Return language dependent information
NLINFO, 4-518
Return numeric date information
ALMANAC, 4-8
Return PIN of child process
GETPROCID, 4-283
Return plabel, NM procedure
HPLOADNMPROC, 4-373
Return program le name being executed
HPMYPROGRAM, 4-389
Return program le name that called intrinsic
HPMYFILE, 4-387
Return program to nonprivileged mode
GETUSERMODE, 4-286
Returns information about a le
FFILEINFO, 4-131
Returns message corresponding to FCHECK
error number
FERRMSG, 4-130
Return source of activation call for process
GETORIGIN, 4-279
Return status for parent/child process
GETPROCINFO, 4-284
Return system dened JCW value
GETJCW, 4-277
Return system time
CLOCK, 4-31
Return system timer information
TIMER, 4-608
Return user-supplied information
GETINFO, 4-275
Return volume information
HPVOLINFO, 4-425
RIN, determine process PIN that locked local
LOCRINOWNER, 4-466
RIN, lock global
LOCKGLORIN, 4-462
RIN, lock local
LOCKLOCRIN, 4-464
RINs, acquire local
GETLOCRIN, 4-278
RINs, free from allocation to job
FREELOCRIN, 4-240
RIN, unlock global
UNLOCKGLORIN, 4-610
RIN, unlock local
UNLOCKLOCRIN, 4-611
Routine header, 1-3
S
Scan and move character strings
NLSCANMOVE, 4-539
Scratch le, close and restore data stack
SORTEND, 4-585
SEARCH
Intrinsic, 4-578
Search array for specied entry/name, 4-578
Search array for specied entry/name
SEARCH, 4-578
Search JCW table and return value
FINDJCW, 4-166
Search String
NLFINDSTR, 4-500
SENDMAIL
Intrinsic, 4-580
Send mail to another process, 4-580
Send mail to another process
SENDMAIL, 4-580
Session information, access
JOBINFO, 4-452
Session, initiate on specied terminal
STARTSESS, 4-599
Session, place in break mode
CAUSEBREAK, 4-28
Set bits in stream JCW
SETJCW, 4-584
Set condition code for calling process
HPSETCCODE, 4-399
SETDUMP
Arm system debugger from process abort,
4-582
Intrinsic, 4-582
SETJCW
Intrinsic, 4-584
Set bits in stream JCW, 4-584
Set logical record pointer for disk le
FPOINT, 4-221
Setting, dene parameter bit, 2-2
Set value of session-level variable
HPCIPUTVAR, 4-305
shareable device, create le
HPFOPEN, 4-331
share data pointer
HPFDUPLICATE, 4-327
Size, alter data segment
ALTDSEG, 4-10
SL procedure, load compatibility mode
LOADPROC, 4-460
SL procedure, unload compatibility mode
UNLOADPROC, 4-609
Software events, 2-12
Software interrupts, enable/disable
FINTSTATE, 4-169
Software library trap handling procedure,
arm/disarm
XLIBTRAP, 4-624
Software traps, 2-12
SORTEND
Close scratch le and restore data stack, 4-585
Intrinsic, 4-585
SORTERRORMESS
Intrinsic, 4-586
Retrieve and print message if fatal error,
4-586
SORTINIT
Initiate SORT program, 4-587
Intrinsic, 4-587
SORTINPUT
Intrinsic, 4-592
Specify how records are supplied to SORT
program, 4-592
Index-19
SORT operation end, release work area
HPSORTEND, 4-403
SORTOUTPUT
Intrinsic, 4-593
Specify how records are output from SORT
program, 4-593
SORT, pass records to
HPSORTINPUT, 4-411
SORT program, how records are output
SORTOUTPUT, 4-593
SORT program, how records are supplied
SORTINPUT, 4-592
SORT program, initiate
SORTINIT, 4-587
SORT program, print statistics on $STDLIST
SORTSTAT, 4-595
SORT, retrieve record from
HPSORTOUTPUT, 4-412
SORTSTAT
Intrinsic, 4-595
Print SORT program statistics on $STDLIST,
4-595
SORT subsystem, initialize
HPSORTINIT, 4-406
SORTTITLE
Intrinsic, 4-596
Print version number/title on $STDLIST,
4-596
Source code extensibility, 1-3
Source of activation call for process, return
GETORIGIN, 4-279
Specify how records are output from SORT
program
SORTOUTPUT, 4-593
Specify how records are supplied to SORT
program
SORTINPUT, 4-592
Specify record output from MERGE program
MERGEOUTPUT, 4-481
Spooled device le, control operations
FDEVICECONTROL, 4-108
STACKDUMP
Execute full stack trace, 4-597
Intrinsic, 4-597
Stack, read logical record from le
FREAD, 4-223
Stack trace, execute full
STACKDUMP, 4-597
STARTSESS
Initiate session on specied terminal, 4-599
Intrinsic, 4-599
Statistics for SORT, print on $STDLIST
HPSORTSTAT, 4-414
Statistics, print MERGE on $STDLIST
HPMERGESTAT, 4-384
Index-20
Status for parent/child process, return
GETPROCINFO, 4-284
Status information for KSAM le
FGETKEYINFO, 4-164
Status information returned, le
FGETINFO, 4-155
Status parameter error, 2-9
String conversion, ASCII to EBCDIC
CTRANSLATE, 4-48
String conversion, EBCDIC to ASCII
CTRANSLATE, 4-48
String conversion, EBCDIK to JIS
CTRANSLATE, 4-48
String conversion, JIS to EBCDIK
CTRANSLATE, 4-48
String, convert ASCII to 16-bit binary
BINARY, 4-19
Strings, compare of dierent length
NLKEYCOMPARE, 4-528
String, translate from/to EBCDIC
NLTRANSLATE, 4-548
Subsystem break trap handling procedure,
arm/disarm
XCONTRAP, 4-622
SUSPEND
Intrinsic, 4-604
Suspend a process, 4-604
Suspend a process
SUSPEND, 4-604
Suspend calling process for time specied
PAUSE, 4-552
SWITCHDB
Change DB register pointer, 4-606
Intrinsic, 4-606
Switch register pointer
SWITCHDB, 4-606
Switch to CM, get plabel
HPLOADCMPROCEDURE, 4-371
Syntax
Format, 2-3
Intrinsic call description, 2-3
System access, services, 1-1
System catalog error message, get or display
HPERRMSG, 4-321
System debugger, arm call from process abort
HPSETDUMP, 4-401
System debugger, arm from process abort
SETDUMP, 4-582
System debugger, disarm from process abort
HPRESETDUMP, 4-394
System-dened les, assign and create process
CREATEPROCESS, 4-43
System dened JCW value, return
GETJCW, 4-277
System intrinsics
Declaration, 2-1
System resources, accessing, 1-1
System supervisor (OP)
Capability, 2-14
System-supplied procedures, 1-1
System time, return
CLOCK, 4-31
System timer information, return
TIMER, 4-608
System trap handling procedure, arm/disarm
XSYSTRAP, 4-626
T
Table search, return JCW value
FINDJCW, 4-166
Tape le, move record pointer
FSPACE, 4-250
Tape, read logical record
FREADBACKWARD, 4-226
Terminal, initiate specied session
STARTSESS, 4-599
TERMINATE
Delete calling process, 4-607
Intrinsic, 4-607
Terminate access to a le
FCLOSE, 4-79
Test mailbox status
MAIL, 4-472
Time and date, return
DATELINE, 4-52
Time, convert from character string to numeric
NLCONVCLOCK, 4-493
Time, format numeric as character string
NLFMTCLOCK, 4-504
Time, format through language dependent
template
NLFMTDATE, 4-508
Time of day, format
FMTCLOCK, 4-186
FMTDATE, 4-187
TIMER
Intrinsic, 4-608
Return system timer information, 4-608
Time, return actual system
CLOCK, 4-31
Title information, print on $STDLIST
HPMERGETITLE, 4-386
Title, print on $STDLIST
HPSORTTITLE, 4-416
MERGETITLE, 4-483
SORTTITLE, 4-596
Transaction, mark beginning of user logging
BEGINLOG, 4-17
Translate string from/to EBCDIC
NLTRANSLATE, 4-548
Trap, enable/disable
HPENBLTRAP, 4-316
Trap handling procedure, arm/disarm
XARITRAP, 4-617
XCONTRAP, 4-622
XLIBTRAP, 4-624
Trap, intrinsic error, 2-12
U
UNLOADPROC
Dynamically unload compatibility mode SL
procedure, 4-609
Intrinsic, 4-609
Unload target procedure
HPUNLOADCMPROCEDURE, 4-423
Unlock le, dynamically
FUNLOCK, 4-252
Unlock global RIN
UNLOCKGLORIN, 4-610
UNLOCKGLORIN
Intrinsic, 4-610
Unlock global RIN, 4-610
Unlock local RIN
UNLOCKLOCRIN, 4-611
UNLOCKLOCRIN
Intrinsic, 4-611
Unlock local RIN, 4-611
Update logical record in disk le
FUPDATE, 4-253
User dened command image, parse
MYCOMMAND, 4-484
User le label, read
FREADLABEL, 4-234
User le label, write
FWRITELABEL, 4-265
User Logging facility, access
OPENLOG, 4-550
user logging facility, close access
CLOSELOG, 4-32
User Logging le, provide information
LOGINFO, 4-468
LOGSTATUS, 4-470
User logging (LG)
Capability, 2-14
User Logging memory buer, ush contents
FLUSHLOG, 4-184
user logging transaction, mark beginning
BEGINLOG, 4-17
user logging transaction, mark end
ENDLOG, 4-64
User Logging, write record
WRITELOG, 4-615
User, return information about
WHO, 4-612
User-supplied information, return
Index-21
GETINFO, 4-275
Using
Itemnum and item pairs, 2-4
Using intrinsics, 2-1
USL le, change length
EXPANDUSLF, 4-66
USL le, delete inactive entries
CLEANUSL, 4-29
USL le, initialize to empty state
INITUSLF, 4-446
Utility functions, request, 1-1
V
Validate and parse le designator
FPARSE, 4-218
Value of session-level variable, set
HPCIPUTVAR, 4-305
Value, retrieve session-level
HPCIGETVAR, 4-301
Value returned, search JCW table
+INDJCW, 4-166
Value, return system dened JCW
GETJCW, 4-277
Variable, set value
HPCIPUTVAR, 4-305
Variable table, delete entry
HPCIDELETEVAR, 4-300
Variable value, retrieve
HPCIGETVAR, 4-301
Version number, print on $STDLIST
HPMERGETITLE, 4-386
MERGETITLE, 4-483
SORTTITLE, 4-596
Version, print on $STDLIST
HPSORTTITLE, 4-416
W
WHO
Intrinsic, 4-612
Return information about user, 4-612
Index-22
Work area, release and end merge
HPMERGEEND, 4-375
Write le
ready, 4-395
WRITELOG
Intrinsic, 4-615
Write record to User Logging le, 4-615
Write logical/physical record from stack to le
FWRITE, 4-255
Write logical record from stack to disk le
FWRITEDIR, 4-263
Write record to User Logging le
WRITELOG, 4-615
Write user le label
FWRITELABEL, 4-265
X
XARITRAP
Arm/disarm arithmetic trap handling
procedure, 4-617
Intrinsic, 4-617
XCONTRAP
Arm/disarm subsystem break trap handling
procedure, 4-622
Intrinsic, 4-622
XLIBTRAP
Arm/disarm software library trap handling
procedure, 4-624
Intrinsic, 4-624
XSYSTRAP
Arm/disarm system trap handling procedure,
4-626
Intrinsic, 4-626
Z
ZSIZE
Alter DB to Z area of compatibility mode
stack, 4-628
Intrinsic, 4-628
">