Guardian Procedure Calls Reference Manual Abstract This manual describes the syntax for most Guardian procedure calls. This manual is for programmers who need to call Guardian procedures from their programs. HP Part Number: 522629-038 Published: April 2014 Edition: J06.03 and all subsequent J-series RVUs, H06.03 and all subsequent H-series RVUs, and G06.27 and all subsequent G-series RVUs.
© Copyright 2014 Hewlett-Packard Development Company, L.P. Legal Notice Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. The information contained herein is subject to change without notice.
Contents About This Manual......................................................................................15 Supported Release Version Updates (RVUs)................................................................................15 Intended Audience..................................................................................................................15 New and Changed Information................................................................................................
CHECKDEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_CHKPT_ Procedure)...........................................................................................................................134 CHECKDEFINE Procedure......................................................................................................136 CHECKMONITOR Procedure.................................................................................................
DEFINEPOOL Procedure........................................................................................................274 DEFINEREADATTR Procedure.................................................................................................277 DEFINERESTORE Procedure...................................................................................................281 DEFINERESTOREWORK[2] Procedures....................................................................................
FILE_READ64_ Procedure......................................................................................................475 FILE_READLOCK64_ Procedure..............................................................................................482 FILE_READUPDATE64_ Procedure...........................................................................................486 FILE_READUPDATELOCK64_ Procedure...................................................................................
FP_IEEE_ROUND_GET_ Procedure..........................................................................................650 FP_IEEE_ROUND_SET_ Procedure...........................................................................................651 6 Guardian Procedure Calls (G)..................................................................652 GETCPCBINFO Procedure.....................................................................................................
MBCS_CHAR_ Procedure......................................................................................................786 MBCS_CHARSIZE_ Procedure................................................................................................789 MBCS_CHARSTRING_ Procedure...........................................................................................791 MBCS_CODESETS_SUPPORTED_ Procedure.............................................................................
12 Guardian Procedure Calls (P).................................................................930 PACKEDIT Procedure.............................................................................................................932 PATHNAME_TO_FILENAME_ Procedure..................................................................................934 POOL_CHECK_ Procedure.....................................................................................................937 POOL_DEFINE_ Procedure................
PROCESSNAME_CREATE_ Procedure....................................................................................1153 PROCESSOR_GETINFOLIST_ Procedure.................................................................................1156 PROCESSOR_GETNAME_ Procedure....................................................................................1172 PROCESSORSTATUS Procedure............................................................................................1176 PROCESSORTYPE Procedure..............
SETSYSTEMCLOCK Procedure (Superseded by the SYSTEMCLOCK_SET_ Procedure)....................1357 SHIFTSTRING Procedure (Superseded by STRING_UPSHIFT_ Procedure)....................................1359 SIGACTION_ Procedure......................................................................................................1361 SIGACTION_INIT_ Procedure...............................................................................................1362 SIGACTION_RESTORE_ Procedure................................
USEREVENTFILE_REGISTER_ Procedure..................................................................................1473 USERIDTOUSERNAME Procedure (Superseded by USER_GETINFO_ Procedure)..........................1475 USERIOBUFFER_ALLOW_ Procedure.....................................................................................1477 USERNAMETOUSERID Procedure (Superseded by USER_GETINFO_ Procedure).........................1478 USESEGMENT Procedure (Superseded by SEGMENT_USE_ Procedure).....................
Figures 1 2 3 4 5 6 7 8 9 10 Sample TAL Syntax for a Procedure Call..............................................................................34 Syntax With String Output Variable....................................................................................35 Sample C Syntax for a Procedure Call................................................................................36 AWAITIO[X|XL] Operation................................................................................................
38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 PROCESSOR_GETINFOLIST_ Attribute Codes and Value Representations.............................1158 Summary of Processor Types and Models........................................................................1168 Procedures Beginning With the Letter R...........................................................................1190 Procedures Beginning With the Letter S..........................................................................
About This Manual This reference manual describes the syntax of most of the Guardian procedure calls. Supported Release Version Updates (RVUs) This publication supports J06.03 and all subsequent J-series RVUs, H06.03 and all subsequent H-series RVUs, and G06.27 and all subsequent G-series RVUs, until otherwise indicated by its replacement publications. To use increased Enscribe limits, the minimum RVUs are H06.28 and J06.17 with specific SPRs.
• 16 ◦ FILE_PURGE_ Procedure (page 473) ◦ FILE_RENAME_ Procedure (page 496) ◦ FILE_RESTOREPOSITION_ Procedure (page 502) ◦ FILE_SAVEPOSITION_ Procedure (page 504) ◦ FILE_SETKEY_ Procedure (page 506) ◦ FILE_SETSYNCINFO_ Procedure (page 516) ◦ FILE_WRITEUPDATE64_ Procedure (page 536) ◦ FILE_WRITEUPDATEUNLOCK64_ Procedure (page 543) ◦ FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure) (page 550) ◦ FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure) (page 560
Changes to the H06.28/J06.
◦ FILE_LOCKFILE64_ Procedure (page 450) ◦ FILE_LOCKREC64_ Procedure (page 453) ◦ FILE_READ64_ Procedure (page 475) ◦ FILE_READLOCK64_ Procedure (page 482) ◦ FILE_READUPDATE64_ Procedure (page 486) ◦ FILE_READUPDATELOCK64_ Procedure (page 492) ◦ FILE_REPLY64_ Procedure (page 499) ◦ FILE_SETMODENOWAIT64_ Procedure (page 511) ◦ FILE_UNLOCKFILE64_ Procedure (page 518) ◦ FILE_UNLOCKREC64_ Procedure (page 521) ◦ FILE_WRITE64_ Procedure (page 524) ◦ FILE_WRITEUPDATE64_ Procedure (page 53
• • Revised SEGMENT_GETINFOSTRUCT_ Procedure (page 1291) as follows: ◦ Revised description of version parameter. ◦ Added SEGMENT_PIN_REUSED (17) error. ◦ Revised the segmentInfo structure. ◦ Revised considerations related to version checking. Revised Table 53: System-Level Limits (page 1579) to correct the limit and description for System-generated names (5-character form). Changes to the H06.27/J06.
• Added the USEREVENT... Procedures (page 1464): USEREVENT_AWAKE_,USEREVENT_GET_, USEREVENT_SET_, USEREVENT_WAIT, and USEREVENTFILE_REGISTER_. • Added disk subtype 50 (SSD) and 51 (SAS) to Table 47: Device Types and Subtypes (page 1525). Changes to the H06.26/J06.15 RVU Manual (522629–035) • Added a new subsection POOL32_... and POOL64_... Procedures (page 953) that describes the POOL32_... procedures.
◦ Added information about POOL32_... procedures to POOL64_DEFINE_ Procedure (page 959). ◦ Added the new timeout parameters to the PROCESS_GETINFO_ Procedure (page 1005) and PROCESS_GETINFOLIST_ Procedure (page 1012). ◦ Revised the attribute code descriptions for the PROCESS_GETINFOLIST_ Procedure (page 1012) as follows: – Revised the description of attribute code 39 in to specify that it is the “process” file name.
• 22 ◦ POOL64_RESET_MAX_ Procedure (page 972) ◦ SYSTEMCLOCK_SET_ Procedure (page 1408) Modified the following procedures as a part of this RVU: ◦ Updated the Syntax for C Programmers and Parameters for the BINSEM_OPEN_ Procedure (page 101) ◦ Updated Errors for the FILE_WRITEREAD[64]_ Procedures (page 531) ◦ Updated Considerations for the IPUAFFINITY_CONTROL_ Procedure (page 736) ◦ Updated Considerations for the IPUAFFINITY_SET_ Procedure (page 743) ◦ Updated Considerations for the JULIANTIME
Document Organization Section Description Chapter 1: Introduction to Guardian Procedure Calls Gives an overview of the procedure calls and describes the format of a procedure call description Sections 2 through 16 Describes the Guardian procedure calls in alphabetic order Appendix A: Device Types and Subtypes Lists the device types and subtypes (such as disks, printers, terminals, and so on) that are referred to by Guardian procedure calls Appendix B: Reserved Process Names Lists the process names
Notation Conventions Hypertext Links Blue text is used to indicate a hypertext link within text. By clicking a passage of text highlighted in blue, you are taken to the location described. For example: The POOL32_... procedure calls are described under POOL32_... and POOL64_... Procedures (page 953). These links are usually, but not always, followed by a page number. General Syntax Notation This list summarizes the notation conventions for syntax presentation in this manual.
A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: FC [ num ] [ -num ] [ text ] K [ X | D ] address { } Braces A group of items enclosed in braces is a list from which you are required to choose one item.
$process-name.#su-name Line Spacing If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections.
ZCOM-TKN-OBJNAME token-type ZSPI-TYP-STRING. !r !o The !o notation following a token or field name indicates that the token or field is optional. For example: ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. !o Change Bar Notation Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on.
Publishing History Table 1 Document History Part Number Product Version Published 522629-034 N.A August 2012 522629-035 N.A February 2013 522629-036 N.A August 2013 522629-037 N.A February 2014 522629-038 N.A April 2014 HP Encourages Your Comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to: pubs.comments@hp.
1 Introduction to Guardian Procedure Calls System services are tasks such as retrieving a record from a disk, writing a file to a tape, sending messages to other processes, or alerting your process to some kind of system error that the operating system or a subsystem performs on behalf of a program. Your programs can make use of these services by calling appropriate Guardian procedures. For example, using the Guardian READ procedure allows a program to read data from a file.
Table 2 Types of Guardian Procedure Calls Procedure Type Action Programming Manuals DEFINEs Specify DEFINEs by class and attribute values. Guardian Programmer's Guide File system Perform operations, such as input and output, on files (this set of procedures includes Enscribe procedures). Guardian Programmer's Guide Formatter Format output data and convert input data.
and J-series Guardian procedures, see the H-Series Application Migration Guide. Except as noted individually, H-series and J-series procedures are equivalent. For further information about how to use the operating system features, see the Guardian Programmer's Guide. Superseded Guardian procedures continue to be supported for compatibility and are still documented in this manual.
Header Files for Guardian Procedure Like all procedures in an application program, HP-supplied Guardian procedures must be declared before they can be called. A header file is a collection of declarations to facilitate compiling other source code that uses those declarations. Header files in $SYSTEM.SYSTEM contain many of the Guardian procedure declarations for each programming language. For example: • TAL and pTAL external procedure declarations are in $SYSTEM.SYSTEM.EXTDECS0.
Multiplicity of EXTDECS* Historically, multiple versions of the external declarations file were provided for compiling your program to run on previous versions of the operating system as well as on the current version. EXTDECS0 is the current version, EXTDECS1 and EXTDECS are progressively older. This practice continues on G-series, but on H- and J- series the three EXTDECS* files are identical. For further information, see the Guardian Programmer’s Guide.
TAL Syntax for a Guardian Procedure Call An example of the TAL syntax description used in this manual is shown in Figure 1-1. Figure 1 Sample TAL Syntax for a Procedure Call The numbered items in the diagram are described below: 1 This indicates that the procedure is a function procedure; it returns a value of the indicated type (in this case INT) when referenced in an expression. You can specify the variable as retval, status, error^code or some other appropriate name in other function procedure calls.
ref:x means that this is a reference parameter, that is, the address of the parameter is passed. (The statements within the program must access the actual parameter contents indirectly through the parameter location.) x indicates the number of elements the parameter contains. In this example, * indicates that the number of elements in the nodename parameter depends on another variable (in this case, length). .EXT means the parameter is a reference parameter accessed by an extended pointer.
the called Guardian procedure, because it might have written over the return address that was stored in the local stack. Which Guardian procedures actually switch stack might change from RVU to RVU and will differ by processor type. C Syntax for a Guardian Procedure Call C syntax is presented in this manual in addition to TAL syntax. Where necessary, considerations for C programmers are also presented.
Examples • This example is of a function that returns the addresses and their lengths. Note that if the length is 0, the address is not significant. typedef struct { void * baseAddress; intlength; } globalLocation[4]; extern extern extern extern extern extern extern extern char char char char char char char char _data_start; _data_end; _sdata_start; _sdata_end; _sbss_start; _sbss_end; _bss_start; _bss_end; void GETGLOB (globalLocation g) { g[0].baseAddress=&_data_start; g[0].
2 Guardian Procedure Calls (A-B) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letters A through B. Table 3 lists all the procedures in this section.
ABEND Procedure (Superseded by PROCESS_STOP_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations NetBatch Considerations OSS Considerations Messages Examples Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The ABEND procedure deletes a process or process pair and signals that the deletion was caused by an abnormal condition.
Syntax for TAL Programmers CALL ABEND ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ process-id ] stop-backup ] error ] compl-code ] termination-info ] spi-ssid ] length ] text ] ); ! ! ! ! ! ! ! ! i i o i i i i i Parameters process-id input INT:ref:4 indicates the process that is to be stopped. The value you enter can be either: • Omitted or zero (0), meaning "stop myself", or • A four-word array containing the process ID of the process to be stopped, where: [0:2] [3] Process name or creation timestamp .<0:3> Reserved .
The following parameters supply completion-code information, which consists of four items: the completion code, a numeric field for additional termination information, a subsystem identifier in SPI format, and an ASCII text string. These items have meaning in the call to ABEND only when a process is stopping itself. compl-code input INT:value is the completion code to be returned to the creator process in the ABEND system message and, for a terminating OSS process, in the OSS termination status.
Considerations • Differences between ABEND and STOP procedures When used to stop the calling process, the ABEND and STOP procedures operate almost identically; they differ in the system messages that are sent and the default completion codes that are reported. In addition, ABEND, but not STOP, causes a saveabend file to be created if the process' SAVEABEND attribute is set to ON. See the Inspect Manual for information about saveabend files.
other processes can stop the process. The stop mode, set by the SETSTOP procedure, is defined below: • 0 ANY other process can stop the process. 1 ONLY the process qualified by the above rules can stop the process. 2 NO other process can stop the process. Returning control to the caller before the process is stopped When error is 0, ABEND returns control to the caller before the specified process is actually stopped.
OSS Considerations • When an OSS process is stopped by the ABEND procedure, either by calling the procedure to stop itself or when some other process calls the procedure, the OSS parent process receives a SIGCHLD signal and the OSS process termination status. For details on the OSS process termination status, see the wait(2) function reference page either online or in the Open System Services System Calls Reference Manual.
ACTIVATEPROCESS Procedure (Superseded by PROCESS_ACTIVATE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations OSS Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The ACTIVATEPROCESS procedure returns a process or process pair from the suspended state to the ready state.
Considerations • When ACTIVATEPROCESS is called on a Guardian process, the caller must be the super ID (255,255), the group manager (n,255) of the process access ID, or a process with the same process access ID as the process or process pair being activated. For more information about the process access ID, see the PROCESSACCESSID procedure Considerations (page 1131) and the Guardian Programmer's Guide.
ADDDSTTRANSITION Procedure (Superseded by DST_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary The ADDDSTTRANSITION procedure allows a super-group user (255,n) to add an entry to the daylight-saving-time (DST) transition table. This operation is allowed only when the DAYLIGHT_SAVING_TIME option in the system is configured to the TABLE option.
local civil time (LCT) = local standard time (LST) + offset Condition Code Settings < (CCL) indicates that you: • Are not a super-group user (255,n) • Loaded the DST table inconsistently (that is, the DST table contains an overlap of entries) • Were loading the DST table at the same time someone else was loading the DST table = (CCE) indicates that the DST table was loaded successfully. > (CCG) is not returned from ADDDSTTRANSITION.
ADDRESS_DELIMIT[64]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Address-Descriptor Bit Fields Reserved Segment ID Values Considerations Example Related Programming Manual Summary The ADDRESS_DELIMIT[64]_ procedures obtain the addresses of the first and last bytes of a particular area of the caller's logical address space. They can also obtain a set of flags that describe the area, and the logical segment ID of the area.
Parameters address input EXTADDR:value (for ADDRESS_DELIMIT_) EXT64ADDR:value (for ADDRESS_DELIMIT64_) is a relative address contained within the address area about which information is desired. Note that address is an address passed by value, not a pointer passed as a reference parameter.
error-detail output INT .EXT:ref:1 (for ADDRESS_DELIMIT_) INT .EXT64:ref:1 (for ADDRESS_DELIMIT64_) returns additional error information when an error value of 3 (bounds error) is returned. For details, see Returned Value. Returned Value INT Outcome of the call. One of these values defined in kmem.h for C and KMEM for pTAL: 0 ADDR_OK No error; the requested values are returned. 2 ADDR_PARAM Parameter error; address parameter was missing.
Bit field Indicates that the segment is SEG_EXTENSIBLE_MASK <14> Extensible. SEG_RESIDENT_MASK <15> Resident. Reserved Segment ID Values The reserved segment ID values that can be returned by the segment-id parameter lie in the range -109 through -2 (65427 through 65534). These values are used internally to identify various types of segments allocated by the operating system, such as process stacks, global data, various kinds of code, and certain special segments.
! segment^ID ! , ERROR^DETAIL); IF ERROR <> 0 THEN CALL ERROR^HANDLER; Related Programming Manual For programming information about the ADDRESS_DELIMIT[64]_ procedures, see the Guardian Programmer's Guide.
ADDRTOPROCNAME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure can be used only with TNS code. A comparable service is provided for accelerated code and native code using the HIST_INIT_ procedure with the HO_Init_Address option.
stack-env input INT:value is the target procedure’s code space identifier in the stack marker ENV register format. Only these fields in stack-env are significant: <4> Library bit <7> System code bit <11:15> Space ID bits proc-name output STRING .EXT:ref is an ASCII string into which is returned the symbolic procedure name corresponding to the code location specified by p-reg, stack-env, and the optional pin. proc-name-size input INT:value is the size (in bytes) of the caller's proc-name buffer.
<4> Entry point bit <5> Variable bit <6> Extensible bit <7:15> PEP number pin input INT:value specifies that p-reg and stack-env see the process identified by pin rather than the calling process. The pin parameter can be supplied only by privileged callers. Returned Value INT A file-system error code that indicates the outcome of the call: 0 Successful call; the procedure name is deposited into proc-name for proc-name-length bytes. 11 A procedure name was not found.
ELSE OFFSET := P^REG '-' BASE; ADDRTOPROCNAME Procedure 57
ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE[64]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The ALLOCATESEGMENT procedure allocates a selectable extended data segment for use by the calling process. This procedure can create read/write segments or read-only segments.
Parameters segment-id input INT:value is the number by which the process chooses to refer to the segment. Segment IDs are in these ranges: 0-1023 Can be specified by user processes. Other IDs Are reserved for HP software. No nonprivileged process can supply a segment ID greater than 2047. segment-size input INT(32):value specifies the size (in bytes) of the segment to be allocated. Flat segment size: • For G04.
If a segment is being shared by the PIN method (see pin-and-flags), this rule applies to the sharers: • The segment-size parameter must be omitted and the size of the segment is the same as that from the initial ALLOCATESEGMENT call. If a segment is being shared by the file-name method (see pin-and-flags), these rules apply to the sharers: • The segment-size parameter is optional. If the segment is a read-only segment, the default segment size is the length of the file (EOF).
<3> If 1, requests allocation of a “shared segment” that is shared by the filename method. A shared segment is an extended data segment that can be shared with other processes in the same processor. The file-name parameter must be supplied when this type of shared segment is allocated. (It is with the pin-and-flags parameter that sharing is specified.
Considerations • Preventing automatic temporary file purge ALLOCATESEGMENT opens the swap file for read/write protected access. A process can prevent the automatic file purge of a temporary swap file by opening the file for read-only shared access before the segment is deallocated.
! allocates a shared segment, which is shared ! using the PIN method with the segment given by ! SEGMENT^ID in the process identified by PIN STATUS := ALLOCATESEGMENT (SEGMENT^ID, , FILENAME, %50000); ! allocates a shared segment, shared using the ! file name method ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE[64]_ Procedures) 63
ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Function Codes Considerations OSS Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The ALTER procedure changes certain attributes of a disk file that are normally set when the file is created.
partonly input INT:value if present, specifies for partitioned files whether the function is to be performed for all partitions of the file (if the value is zero (0)), or just for the named partition (if the value is 1). Nonpartitioned files use zero. If omitted, zero (0) is assumed. A value of 1 cannot be specified for some functions, as noted below. If a function would affect alternate-key files, then a value of 1 will prevent this.
Table 4 ALTER Function Codes (continued) Code Description The expiration date is not changed for associated alternate-key files, but is changed for the secondary partitions of a partitioned file (unless the value of partonly is 1). The expiration date for a temporary file cannot be set with ALTER, since temporary files must be purged when closed. Considerations • The file cannot be opened when ALTER is called. • The security on the file must allow the caller to have read and write access.
ALTERPRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The ALTERPRIORITY procedure is used to change the execution priority of a process or process pair.
Condition Code Settings < (CCL) indicates that ALTERPRIORITY failed, or no process designated as process-id exists. = (CCE) indicates that the priority of the process is altered. > (CCG) does not return from ALTERPRIORITY. Considerations When ALTERPRIORITY is called on a Guardian process, the caller must be either the super ID (255,255), the group manager (n,255) of the process access ID, or a process with the same process access ID as the process or process pair whose priority is being changed.
ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Functions Trap Handler Activation and Termination Considerations Additional Considerations for Native Systems OSS Considerations Example Related Programming Manual Summary NOTE: This procedure cannot be called by OSS or native processes; use the signal procedures. TNS Guardian processes must continue to use this procedure.
trapstack-addr input INT:value is an address specifying the local data area for the application process' trap handler. The trapstack-addr parameter also indicates where the trap number and stack marker at the time of the trap are passed to the application process. If trapstack-addr has a value < 0, then trap handling is disabled and any trap results in the process being stopped with a process deletion (ABEND) message.
12 No memory available 13 Uncorrectable memory error 'L'[-3] Value of ‘S’ at the time of the trap; it is -1 if the trap occurs in a protected code area (see Considerations) 'L'[-2] Value of ‘P’ at the time of the trap; the ‘P’ value associated with the space ID in ‘L’[-5] completely identifies the location of the trap 'L'[-1] Value of the hardware ENV register at the time of the trap 'L'[0] Value of ‘L’ at the time of the trap The locations ‘L'[-5] through ‘L'[0] are referred to as trap variable
where num-locals is a LITERAL defining the number of words of local storage needed (see the next consideration). • Base-address equivalencing and declaring local variables Any local variables in the application program's trap-handling procedure must be declared relative to the L register by using base-address equivalencing. For example: INT I='L' + 9; STRING .
on TNS systems, another overflow trap immediately occurs and on native systems, the process abends.) ◦ Resume with no modifications (modifying the overflow or trap bit of the trap ENV variable is permitted) after a trap 4 (loop timer interrupt). See the “Resuming at the point of the trap” consideration below. ◦ Jump to a restart point by changing the trap variables P, L, ENV, space ID, and S. See the “Resuming at the point of the trap” consideration below.
• How to avoid writing over the application's data stack If ‘L'[-3] (the value of ‘S' at the time of the trap) is -1, the trap handler should not resume from the trap handler without first changing ‘L'[-3] to a more appropriate value. Otherwise, ‘G'[0] through ‘G'[10] of the application's data stack are overwritten.
. . CALL ARMTRAP ( 0, $LMIN ( LASTADDR , %77777 ) - 500 ); END; PROC MAIN PROC; BEGIN CALL TRAPPROC; . . . END; Related Programming Manual For programming information about the ARMTRAP trap-handling procedure, see the Guardian Programmer's Guide.
AWAITIO[X|XL] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Operation and Completion Summary Considerations OSS Considerations Related Programming Manual Summary The AWAITIO, AWAITIOX, and AWAITIOXL procedures are used to complete a previously initiated I/O operation. Use AWAITIO with the 16-bit versions such as READ, WRITEREAD, and so forth.
Syntax for C Programmers #include _cc_status AWAITIO ( short _near *filenum ,[ short _near *buffer-addr ] ,[ unsigned short _near *count-transferred ] ,[ __int32_t _near *tag ] ,[ __int32_t timelimit ] ); #include _cc_status AWAITIOX ( short _far *filenum ,[ __int32_t _far *buffer-addr ] ,[ unsigned short _far *count-transferred ] ,[ __int32_t _far *tag ] ,[ __int32_t timelimit ] ,[ short _far *segment-id ] ); #include short AWAITIOXL ( short
Parameters filenum input, output INT:ref:1 (for AWAITIO) INT .EXT:ref:1 (for AWAITIOX[L]) is the number of an open file. If a particular filenum is passed, AWAITIO[X|XL] applies to that file. If filenum is passed as -1, the call to AWAITIO[X|XL] applies to the oldest incomplete operation pending on each file. The specific action depends on the value of the timelimit parameter (see the timelimit parameter below). AWAITIO[X|XL] returns into filenum the file number associated with the completed operation.
timelimit input INT(32):value indicates whether the process waits for completion instead of checking for completion. If timelimit is passed as: > 0D A wait-for-completion is specified. The timelimit parameter specifies the maximum time (in .01-second units) from the time of the AWAITIO[X|XL] call that the application process can wait (that is, be on a wait list) for completion of a waited-for operation. See “Queue files” in Considerations (page 81). = -1D An indefinite wait is indicated.
Figure 4 AWAITIO[X|XL] Operation NOTE: AWAITIOXL returns the error code directly. How AWAITIO[X|XL] completes depends on whether the filenum parameter specifies a particular file or any file and on what the value of timelimit is when passed with the call. The action taken by AWAITIO[X|XL] for each combination of filenum and timelimit is summarized in Table 5. Table 5 AWAITIO[X|XL] Action Particular File (filenum = a file number) timelimit = 0 timelimit <> 0 CHECK for any I/O completion on filenum.
NOTE: This table assumes that SETMODE function 30 has been set. Considerations • Completing nowait calls Each nowait operation initiated must be completed with a corresponding call to AWAITIO[X|XL].
NOTE: Use AWAITIO only with the 16-bit I/O versions of the above procedures, such as READ, WRITEREAD, and so forth. You can use AWAITIOX with any versions of the above procedures, including READX, WRITEREADX, and so forth. You can use AWAITIOXL with SERVERCLASS_SENDL_ , READUPDATE[X|XL], and any versions of the above procedures. • Completion tag values A tag -30D returned by AWAITIO signals completion of a nowait open; a tag -29D returned by AWAITIO signals completion of a nowait backup open.
this option can use the tag parameter to keep track of multiple I/O operations associated with a file open. • Operation timed out If an error indication is returned on a call where either timelimit = 0 or filenum = -1 was specified, and a subsequent call to FILE_GETINFO_ or FILEINFO shows that an error 40 occurred, the operation is considered incomplete and AWAITIO[X|XL] must be called again.
Related Programming Manual For programming information about the AWAITIO[X|XL] file-system procedures, see the Guardian Programmer's Guide.
BACKSPACEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The BACKSPACEEDIT procedure sets the current record number of an IOEdit file to that of the line preceding what was the current record before the call.
BINSEM_CLOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manuals Summary The BINSEM_CLOSE_ procedure closes access to a binary semaphore. Syntax for C Programmers #include short BINSEM_CLOSE_ ( __int32_t semid ); Syntax for TAL Programmers error := BINSEM_CLOSE_ ( semid ); ! i Parameters semid input INT (32):value specifies a binary semaphore ID.
Considerations NOTE: • There are additional considerations for privileged callers. The close operation and the state of the binary semaphore ◦ If the binary semaphore is locked by the calling process, then the value of error is 4045, the state of the binary semaphore remains unchanged, and the specified binary semaphore ID can continue to provide access to the binary semaphore.
BINSEM_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value General Considerations for Binary Semaphores Considerations Example Related Programming Manuals Summary The BINSEM_CREATE_ procedure creates, opens, and locks a binary semaphore.
Returned Value INT Outcome of the call: 0 No error. 22 Bounds error. The semid parameter cannot be written to by the calling process. 29 Required parameter missing. The semid and security parameters must be specified. 4002 Either the process or the processor has reached the maximum number of user semaphores it can open concurrently. The corresponding errno value is ENOENT. NOTE: The number of binary semaphores a processor can have open on systems running H06.17 and later H-series RVUs and J06.
◦ BINSEM_LOCK_ which locks a binary semaphore. ◦ BINSEM_UNLOCK_ which unlocks a binary semaphore. ◦ BINSEM_CLOSE_ which closes access to a binary semaphore. ◦ BINSEM_FORCELOCK_ which takes the lock from a process that has the lock. ◦ BINSEM_ISMINE_ which returns whether or not the caller is the current owner of the binary semaphore. NOTE: The BINSEM_ISMINE_procedure is supported on systems running H06.12 and later H-series RVUs and J06.03 and later J-series RVUs.
BINSEM_FORCELOCK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manuals Summary The BINSEM_FORCELOCK_ procedure forces a lock on a binary semaphore. This procedure is used when it is not possible to lock a binary semaphore with the BINSEM_LOCK_ procedure.
4045 Deadlock. The binary semaphore was forsaken before the procedure call, and it is now locked. The corresponding errno value is EDEADLK. 4103 Already locked. The binary semaphore was locked by the calling process before the procedure call, and it remains locked. The corresponding errno value is EALREADY. Considerations NOTE: • • There are additional considerations for privileged callers.
BINSEM_GETSTATS_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manuals Summary The BINSEM_GETSTATS_ procedure returns counter statistics for one or more binary semaphores for a specified process. Additionally, BINSEM_GETSTATS_ can clear counters and reset the maximum number of contenders. NOTE: The BINSEM_GETSTATS_ procedure is supported on systems running H06.25 and later H-series RVUs and J06.14 and later J-series RVUs.
options input INT (32):value controls the behavior of BINSEM_GETSTATS_ for a specified binary semaphore. Set to one of the following: BINSEM_STAT_OPT_DEFAULT obtains counter statistics. BINSEM_STAT_OPT_CLEAR obtains statistics and clear counters. BINSEM_STAT_OPT_RESETMAX obtains statistics and resets the maximum number of contenders. BINSEM_STAT_OPT_RESET_ALL obtains statistics, resets the maximum number of contenders, and resets all of the counters. statsP output INT .
Recovery: Check to make sure the specified process is active. Run the program calling BINSEM_GETSTATS_ on the same processor where the process of interest is running. 4001 BINSEM_RET_EPERM This process does not have the appropriate access ID to obtain statistics on the process of interest. Recovery: Only users with appropriate privileges to a process are able to successfully call BINSEM_GETSTATS_.
HP recommends calling the BINSEM_STAT_VERSION_ procedure prior to BINSEM_GETSTATS_ to ensure the BINSEM_GETSTATS_ procedure matches the implementation version of BINSEM_GETSTATS_. See also the BINSEM_STAT_VERSION_ Procedure (page 103). Related Programming Manuals For programming information about the BINSEM_GETSTATS_ procedure, see the Guardian Programmer's Guide.
BINSEM_ISMINE_Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The BINSEM_ISMINE_procedure allows an application to query whether it is the current owner of any of the semaphores it has obtained access to via a call to either the BINSEM_CREATE_procedure or the BINSEM_OPEN_procedure. The BINSEM_ISMINE_ procedure takes as its parameter the semaphore ID, returned by either the BINSEM_CREATE_procedure or the BINSEM_OPEN_ procedure.
Example IF BINSEM_ISMINE_(semid) THEN ...
BINSEM_LOCK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The BINSEM_LOCK_ procedure locks a binary semaphore. Syntax for C Programmers #include short BINSEM_LOCK_ ( __int32_t semid ,__int32_t timeout ); Syntax for TAL Programmers status := BINSEM_LOCK_ ( semid ,timeout ); ! i ! i Parameters semid input INT (32):value specifies the binary semaphore ID.
Considerations NOTE: • • There are additional considerations for privileged callers. The lock operation and the state of the binary semaphore ◦ If the binary semaphore is unlocked before the specified timeout has elapsed, then the value of status is 0 and the state of the binary semaphore becomes locked by the calling process.
BINSEM_OPEN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manuals Summary The BINSEM_OPEN_ procedure opens a binary semaphore. Syntax for C Programmers #include short BINSEM_OPEN_ ( __int32_t *semid ,short *processhandle ,__int32_t proc-semid ); Or alternatively, as of the H06.25, J06.14, and subsequent RVUs: #include
proc-semid input INT (32):value specifies the binary semaphore ID of an open binary semaphore. The proc-semid value can be obtained by a previous call to the BINSEM_CREATE_ or BINSEM_OPEN_ procedure. The processhandle must designate the process in which that call occurred. Returned Value INT Outcome of the call: 0 No error. 22 Bounds error. The semid parameter cannot be written by the calling process or processhandle cannot be read from the calling process. 29 Required parameter missing.
BINSEM_STAT_VERSION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Related Programming Manuals Summary The BINSEM_STAT_VERSION_ procedure accepts a version number defined in kbinsem.h for the BINSEM_GETSTATS_ procedure and checks whether or not it matches the implementation version of BINSEM_GETSTATS_. NOTE: The BINSEM_STATS_VERSION_ procedure is supported on systems running H06.25 and later H-series RVUs and J06.
Considerations • Depending on the nature of changes in the interface and the data of interest to the application, the application might work even when a version mismatch occurs; however, HP recommends recompiling the application whenever a version check fails. • See also the BINSEM_GETSTATS_ Procedure (page 93). Example ret-val := BINSEM_STAT_VERSION_( version ); Related Programming Manuals For programming information about the BINSEM_STAT_VERSION_ procedure, see the Guardian Programmer's Guide.
BINSEM_UNLOCK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Related Programming Manuals Summary The BINSEM_UNLOCK_ procedure unlocks a binary semaphore. Syntax for C Programmers #include short BINSEM_UNLOCK_ ( __int32_t semid ); Syntax for TAL Programmers error := BINSEM_UNLOCK_ ( semid ); ! i Parameter semid input INT (32):value specifies a binary semaphore ID.
Considerations • • The unlock operation and the state of the binary semaphore ◦ If the binary semaphore is locked by the calling process, then the value of error is 0 and the state of the binary semaphore becomes unlocked. ◦ If the binary semaphore is either locked by another process, unlocked, or forsaken, then the value of error is 4001 and the state of the binary semaphore remains unchanged. For more information about binary semaphores, see General Considerations for Binary Semaphores (page 89).
BREAKMESSAGE_SEND_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The BREAKMESSAGE_SEND_ procedure sends a break-on-device message to a specified process.
Returned Value INT A file-system error code that indicates the outcome of the call. A successful indication implies only that the message has been sent, not that it has been received. Considerations If processhandle designates a member of a named process pair, and if a failure or a path switch occurs, delivery of the break-on-device message is automatically retried to the backup process. For detailed information about system messages, see the Guardian Procedure Errors and Messages Manual.
3 Guardian Procedure Calls (C) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter C. Table 3-1 lists all the procedures in this section.
Table 7 Procedures Beginning With the Letter C (continued) CONFIG_GETINFO_BYNAME2_ Procedure CONTIME Procedure CONTROL Procedure CONTROLBUF Procedure CONTROLMESSAGESYSTEM Procedure CONVERTASCIIEBCDIC Procedure CONVERTPROCESSNAME Procedure (Superseded by FILENAME_RESOLVE_ Procedure) CONVERTPROCESSTIME Procedure CONVERTTIMESTAMP Procedure CPU_GETINFOLIST_ Procedure CPUTIMES Procedure CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure) CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ Proc
CANCEL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations Messages Related Programming Manual Summary The CANCEL procedure is used to cancel the oldest incomplete operation on a file opened nowait. The canceled operation might or might not have had effects. For disk files, the file position might or might not be changed.
Considerations • Queue files If a READUPDATELOCK[X] operation is canceled using the CANCEL procedure, the READUPDATELOCK[X] might already have deleted a record from the queue file, which could result in a loss of a record from the queue file. For audited queue files only, your application can recover from a timeout error by calling the ABORTTRANSACTION procedure, when detecting error 40, to ensure that any dequeued records are reinserted into the file.
CANCELPROCESSTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Related Programming Manual Summary The CANCELPROCESSTIMEOUT procedure cancels a process-time timer previously initiated by a call to the SIGNALPROCESSTIMEOUT procedure.
CANCELREQ[L] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Considerations Messages Related Programming Manual Summary The CANCELREQ[L] procedures are used to cancel an incomplete operation, identified by a file number and tag, on a file opened for nowait I/O.
error:= CANCELREQL ( filenum ,[ tag ] ); ! i ! i Parameters filenum input INT:value is the number of an open file, identifying the file whose operation did not complete and is to be canceled. filenum input INT:value is the number of an open file, identifying the file whose operation did not complete and is to be canceled. tag input INT(32):value (for CANCELREQ) INT(64):value (for CANCELREQL) is the tag value passed to the procedure that initialized the I/O operation.
Related Programming Manual For programming information about the CANCELREQ[L] procedures, see the Guardian Programmer's Guide.
CANCELTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Related Programming Manual Summary The CANCELTIMEOUT procedure cancels an elapsed-time timer previously initiated by a call to the SIGNALTIMEOUT procedure.
CHANGELIST Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Example Related Programming Manuals Summary The CHANGELIST procedure is used only when the application program acts as a supervisor or tributary station in a centralized multipoint configuration.
function input INT:value is an integer value specifying what change is to be made: >= 0 changes the poll state bit. In this case, function also specifies the relative address of the particular station address within the address list (0 indicates the first entry, 1 the second entry, and so forth). The parameter value, described below, specifies whether you want the bit to be set or cleared. -1 changes the polling type.
CHECK^BREAK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The CHECK^BREAK procedure tests whether the BREAK key has been typed since the last CHECK^BREAK. CHECK^BREAK is a sequential I/O (SIO) procedure and can be used only with files that have been opened by OPEN^FILE.
Considerations • Default action If a carriage return/line feed (CR/LF) on BREAK is enabled (that is, BREAK ownership is taken by the process), the CR/LF default case sequence is executed on the terminal where BREAK is typed. • For information about terminals, see the Guardian Programmer's Guide. Example BREAK := CHECK^BREAK ( OUT^FILE ); Related Programming Manual For programming information about the CHECK^BREAK procedure, see the Guardian Programmer's Guide.
CHECK^FILE Procedure Summary Syntax for C Programs Syntax for TAL Programmers Parameters Returned Value Operations Considerations Examples Related Programming Manual Summary The CHECK^FILE procedure checks the file characteristics of a specified file. CHECK^FILE is a sequential I/O (SIO) procedure and can be used only with files that have been opened by OPEN^FILE.
Parameters common-fcb or file-fcb input INT:ref:* identifies which file is checked. The common file control block (FCB) can be used for certain types of operations; the common FCB must be used for the operations FILE^BREAKHIT, FILE^ERRORFILE, and FILE^TRACEBACK. Specifying an improper FCB causes an error indication. operation input INT:value specifies which file characteristic is checked. The operations and their associated return values are described in Operations.
Table 8 CHECK^FILE Operations That Return Values operation State of File retval FILE^ABORT^XFERERR Open 0 if the process is not to abort upon detection of a fatal error in the file. 1 if the process is to abort. FILE^ASSIGNMASK1 Any Returns the high-order word of the ASSIGN message field mask in the FCB. This value generally has meaning only after being set by the INITIALIZER procedure. FILE^ASSIGNMASK1 Any Returns the high-order word of the ASSIGN message field mask in the FCB.
Table 8 CHECK^FILE Operations That Return Values (continued) operation State of File retval The device type and subtype are described in Appendix A: Device Types and Subtypes. File types 0-3 are described in the Enscribe Programmer’s Guide. FILE^FNUM Open Returns the file number. If the file is not open, the file number is -1. FILE^LEVEL3^SPOOLING Open 0 if level-3 spooling is disabled. 1 if level-3 spooling is enabled. 0 if there is no logical I/O outstanding.
Table 8 CHECK^FILE Operations That Return Values (continued) operation State of File retval messages; for these, use operation FILE^SYSTEMMESSAGESMANY. FILE^SYSTEMMESSAGESMANY Open Returns the word address within the FCB of a four-word mask indicating which system messages the user handles directly. See SET^FILE for the format. A return of all zeros indicates that the SIO procedures handle all system messages. FILE^TRACEBACK Any 0 if the P-relative address is not appended to all SIO error messages.
Table 9 CHECK^FILE Operations That Return Addresses (continued) operation State of File ret-addr (for native callers) retval (for other callers) [1] through [8] FILE^OPENERSPID^ADDR Open Returns the word address within the FCB of the file opener’s PID. Valid only for C-series format FCBs. FILE^SEQNUM^ADDR Any Returns the word address within the FCB of an INT (32) sequence number. This is the line number of the last record read of an EDIT file.
CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CHECKALLOCATESEGMENT procedure allocates a selectable extended data segment for use by the backup process in a process pair. It is called from the primary process.
back out to the file. CHECKALLOCATESEGMENT must be able to allocate a sufficient number of file extents to contain all memory in the segment. The parameter can be a volume name with a blank subvolume and file; CHECKALLOCATESEGMENT allocates a temporary swap file on the indicated volume. If you do not specify file-name (and if a segment is not being shared using the PIN method), CHECKALLOCATESEGMENT uses the volume of the data stack swap file to create a temporary swap file for the new segment.
29 The segment-id is missing. 30 No message-system control blocks available. 31 Cannot use the PFS, or there is no room in the PFS for a message buffer in either the backup or the primary. 201 Unable to LINK to the backup. Condition Code Settings < (CCL) is set if the error parameter is missing, or there is a bounds error on the error parameter. = (CCE) is set by all other errors (see the error parameter). > (CCG) is never returned from this procedure.
If processes are running in different processors, they can share a segment only if the security requirements are met and the segment is a read-only segment. Callers of [CHECK]ALLOCATESEGMENT can share segments with callers of SEGMENT_ALLOCATE_[CHKPT_]. High-PIN callers can share segments with low-PIN callers. • Sharing flat segments A process cannot share a flat segment with a process that allocated a selectable segment, because the segments reside in different parts of memory.
CHECKCLOSE Procedure (Superseded by FILE_CLOSE_CHKPT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CHECKCLOSE procedure is called by a primary process to close a designated file in its backup process.
Condition Code Settings These settings are obtained from the CLOSE procedure in the backup process; CHECKCLOSE establishes these settings in the primary process: < (CCL) indicates that an invalid file number was supplied or that the backup process does not exist. = (CCE) indicates that the CLOSE was successful. > (CCG) does not return from CHECKCLOSE.
CHECKDEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_CHKPT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CHECKDEALLOCATESEGMENT procedure deallocates an extended data segment from use by the backup process in a process pair.
error output INT .EXT:ref:1 indicates the outcome of the call. This procedure returns all values returned by DEALLOCATESEGMENT in the backup process, plus these file-system errors: 2 The segment ID is invalid or the backup process could not deallocate the segment. 29 The segment-id is missing. 30 No control blocks are available for linking. 31 Cannot use the process file segment (PFS), or the PFS has no room for a message buffer in either the backup process or the primary process.
CHECKDEFINE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The CHECKDEFINE procedure is used to update a backup process with a DEFINE that was changed in the primary process. Syntax for C Programmers This passive backup procedure is not supported in C programs. For a comparison of active backup and passive backup, see the Guardian Programmer's Guide.
• Note that since all DEFINEs are propagated to the backup process when it is created, use of CHECKDEFINE is not necessary unless one or more DEFINEs are changed. • If a call to CHECKDEFINE causes a DEFINE in the backup to be altered, deleted, or added, then the context-change count for the backup process is incremented. Example STRING .EXT define^name[0:23]; LITERAL success = 0; . . define^name ':=' ["=mydefine status := CHECKDEFINE ( define^name ); IF status <> success THEN ...
CHECKMONITOR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Messages Summary The CHECKMONITOR procedure is called by a backup process to monitor the state of the primary process and to return control to the appropriate point (in the backup process) in the event of a failure of the primary process. Syntax for C Programmers This passive backup procedure is not supported in C programs.
Considerations • Takeovers and selectable data segments in use If the stack has never been checkpointed, then at a takeover, the selectable segment in use at the time of the call to the CHECKMONITOR or CHECKSWITCH procedure is put into use.
CHECKOPEN Procedure (Superseded by FILE_OPEN_CHKPT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Messages Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CHECKOPEN procedure is called by a primary process to open a designated file for its backup process.
backerror output INT:ref:1 returns one of these values: Š0 is the file-system error number reflecting the call to FILE_OPEN_ in the backup process. -1 indicates that the backup process is not running or that the checkpoint facility could not communicate with the backup process. Condition Code Settings These settings are obtained from the FILE_OPEN_ procedure in the backup process: < (CCL) indicates that the open failed. The file-system error number returns in backerror.
CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The CHECKPOINT procedure is called by a primary process to send information about its current executing state to its backup process.
count-n input INT:value The use of this parameter depends on the presence or absence of the corresponding buffer-n parameter: • If buffer-n is present, then count-n specifies the number of words to be checkpointed. • If buffer-n is absent, then count-n is the filenum of a file whose file synchronization block is to be checkpointed. NOTE: If the message is too large (that is, the total of the stack size and the counts of all buffers and the size of all file synchronization blocks is too big), status.
procedure for that file. If file sync block checkpointing is performed, FILE_GETINFO_ returns (in its last-error parameter) the status of the call to GETSYNCINFO (usually, last-error = 0). • Unable to communicate with backup If an "unable to communicate with backup" error (that is, status.<0:7> = 1) occurs, this normally indicates either that the backup process does not exist or that a system resource problem exists.
CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The CHECKPOINTMANY procedure (like the CHECKPOINT procedure) is called by a primary process to send information about its current executing state to its backup process.
The array has this form: descriptors[0] [n] [n+1] +----------------------------------------+ | number of items to be checkpointed | |----------------------------------------| |----------------------------------------| |-------- descriptors pairs -------------| |----------------------------------------| . . . . If the first word of the pair contains -1, the pair describes a file synchronization block item for the file whose file number is in the second word of the pair.
Considerations • Invalid parameter If an attempt is made to checkpoint the data area used by CHECKPOINTMANY for system-oriented stack maintenance, it returns an "invalid parameter" error (that is, status.<0:7> = 3). If status.<0:7> = 3, then status.<8:15> has this meaning: status.
• Identification of the backup process The system identifies the process to be affected by the CHECKPOINTMANY operation from the process' mom field in the process control block (PCB). For named process pairs, this field is automatically set up during the creation of a backup process.
CHECKPOINTMANYX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The CHECKPOINTMANYX procedure (like the CHECKPOINTX procedure) is called by a primary process to send information about its current executing state to its backup process. The checkpoint information enables the backup process to recover from a failure of the primary process in an orderly way.
descriptors input INT .EXT:ref:* is an array that describes the items (data blocks or file synchronization blocks) to be checkpointed. The first word of the array, descriptors[0], contains the number of items to be checkpointed. The rest of the array consists of sets of words, with each set containing five words and describing one item. The array has this form: [0] Contains the number of items to be checkpointed. Each item consists of a set of five words. If the item is a file: [0:1] Equals -1D.
Considerations • Checkpointing the stack Checkpointing the entire data stack has the effect of providing a restart point for the backup process. The stack-origin parameter gives you the option of specifying how far into the stack to start checkpointing. Although native stacks grow downward while TNS stacks grow upward, the effect is the same—all data from stack-origin to the growing tip of the stack is checkpointed.
If the stack-origin parameter is omitted, the stack is not checkpointed. You can, however, include the stack-origin parameter without checkpointing the stack by setting stack-origin to -1. • Checkpointing data areas Checkpointing specific variables involves using the descriptors parameter to specify the addresses of data areas and the number of bytes to be checkpointed.
have a segment with that segment ID, an error is returned and no data or file information is checkpointed. • Extended addresses must be relative; they cannot be absolute. Extended addresses cannot be in the user code space.
• – The address was invalid; for example, the address was in an extended data segment, but either the segment ID was not allocated, the segment ID was an invalid segment number, or there was a bounds error on the area. – The total message size was too large (over 32 KB). Increased file limits for key-sequenced files The CHECKPOINTMANYX procedure can checkpoint the file synchronization blocks of file numbers passed to it in the descriptors parameter. In H06.28/J06.
CHECKPOINTX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The CHECKPOINTX procedure (like the CHECKPOINTMANYX procedure) is called by a primary process to send information about its current executing state to its backup process. The checkpoint information enables the backup process to recover from a failure of the primary process in an orderly manner.
segment-idn input INT:value contains the segment ID of the extended data segment if the bufferx-n parameter is provided and the data block to be checkpointed is in an extended data segment. If segment-idn is omitted or equal to -1, the data block is assumed to be either in the flat segment, in the selectable segment currently in use, or on the stack, depending on the address provided.
Considerations • Checkpointing the stack Checkpointing the entire data stack has the effect of providing a restart point for the backup process. The stack-origin parameter gives you the option of specifying how far into the stack to start checkpointing. Although native stacks grow downward while TNS stacks grow upward, the effect is the same—all data from stack-origin to the tip of the stack is checkpointed.
If the stack-origin parameter is omitted, the stack is not checkpointed. You can, however, include the stack-origin parameter without checkpointing the stack by setting stack-origin to -1. • Checkpointing data areas Checkpointing specific variables involves specifying the address of a data area in the bufferx-n parameter and a byte count in count-n. Differences in data layout between a TNS stack and a native main stack cause some restrictions in the way native processes address these buffers.
of the addressable area of the segment in the backup process is not checkpointed. If the backup process does not have a segment with that segment ID, an error is returned and no data or file information is checkpointed. • Extended addresses must be relative; they cannot be absolute. Extended addresses cannot be in the user code space.
– The address was in an extended data segment, but either the segment ID was not allocated, the segment ID was an invalid segment number, or there was a bounds error on the area. – The total message size was too large (over 32.5 kilobytes for a TNS process or 50 kilobytes for a native process). – An invalid combination of parameters occurred: There was a count, but no buffer; or there was a buffer, but no count; or there was a buffer and a segment ID, but no count.
CHECKRESIZESEGMENT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Summary The CHECKRESIZESEGMENT procedure complements the RESIZESEGMENT procedure. Syntax for C Programmers This passive backup procedure is not supported in C programs. For a comparison of active backup and passive backup, see the Guardian Programmer's Guide.
CHECKSETMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary The CHECKSETMODE procedure allows a primary process of a process pair to propagate SETMODE operations to the backup process of the pair. Syntax for C Programmers This passive backup procedure is not supported in C programs. For a comparison of active backup and passive backup, see the Guardian Programmer's Guide.
error output INT .EXT:ref:1 the error that occurred on the operation. These file-system errors are returned from CHECKSETMODE: 2 The function parameter is not one of the allowed values. 29 The filenum or function parameter is missing. 30 No message control blocks are available. 31 Cannot use the process file segment (PFS), or the PFS has no room for a message buffer in either the backup process or the primary process. 201 Unable to link to the backup process.
CHECKSWITCH Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary The CHECKSWITCH procedure is called by a primary process to cause the duties of the primary and backup processes to be interchanged. The call to CHECKSWITCH contains an implicit call to the CHECKMONITOR procedure, so that the caller becomes the backup and monitors the execution state of the new primary process.
the current backup to become the primary process and to begin processing from the latest call to the CHECKPOINT[MANY][X] procedure. • Identification of the backup process The system identifies the process to be affected by the CHECKSWITCH operation from the process' mom field in the process control block (PCB). For named process pairs, this field is automatically set up during the creation of a backup process.
CHILD_LOST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The CHILD_LOST_ procedure examines a system message to determine whether it indicates that a specified process or process pair has been lost.
-100 Remote processor down. -101 Process deletion. -110 Connection to remote system lost. If any other system message is supplied, a status value of 5 is returned. processhandle input INT .EXT:ref:10 is the process handle of the process to be checked. For a check involving a named process pair, it is the process handle of any present or former member of that pair. Returned Value INT A status value that indicates the result of the check: 0 Process or process pair is not lost.
-101 Process deletion Same process Same name and sequence number -110 Connection to remote node lost Same node Same node Example status := CHILD_LOST_ ( sys^message:length, proc^handle ); Related Programming Manual For programming information about the CHILD_LOST_ procedure, see the Guardian Programmer's Guide.
CLOSE Procedure (Superseded by FILE_CLOSE_Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Messages Related Programming Manuals Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development The CLOSE procedure closes an open file. Closing a file terminates access to the file.
Condition Code Settings < (CCL) indicates that the file was not open or, for $RECEIVE or the TFILE, there is an outstanding operation using an active transaction. = (CCE) indicates that the CLOSE was successful. > (CCG) does not return from CLOSE. Considerations • Returning space allocation after closing a file Closing a disk file causes the space that is used by the resident file control block to be returned to the system main-memory pool if the disk file is not open concurrently.
CLOSE^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The CLOSE^FILE procedure closes a specified file. CLOSE^FILE is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
tape-disposition.<13:15> denotes: 0 Rewind, unload, do not wait for completion. 1 Rewind, unload, do not wait for completion. 2 Rewind, leave online, do not wait for completion. 3 Rewind, leave online, wait for completion. 4 Do not rewind, leave online. Other input values result in no error if the file is a tape device; the control action might be unpredictable. Returned Value INT Either a file-system or a SIO procedure error code that indicates the outcome of the close operation.
Related Programming Manual For programming information about the CLOSE^FILE procedure, see the Guardian Programmer's Guide.
CLOSEALLEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Considerations Related Programming Manual Summary The CLOSEALLEDIT procedure closes all open IOEdit files. Calling CLOSEALLEDIT is equivalent to calling the CLOSEEDIT or CLOSEEDIT_ procedure (without the keep-filenum parameter) for each file that has been opened by the OPENEDIT or OPENEDIT_ procedure and that has not been closed.
CLOSEEDIT Procedure (Superseded by CLOSEEDIT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary NOTE: The CLOSEEDIT procedure is supported for compatibility with previous software. For new development, the CLOSEEDIT_ procedure should be used instead. The CLOSEEDIT procedure closes a specified file that was opened by the OPENEDIT or OPENEDIT_ procedure.
CLOSEEDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The CLOSEEDIT_ procedure closes a specified file that was opened by the OPENEDIT or OPENEDIT_ procedure. The procedure writes to disk any file updates that are still buffered, optionally closes the file through the file system, and finally deallocates all data blocks in the EDIT file segment (EFS) that are associated with the file.
COMPLETEIOEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The COMPLETEIOEDIT procedure informs IOEdit that an outstanding I/O request has finished. Whenever AWAITIO[X] reports the completion of an I/O request on a file that is (or could be) an IOEdit file, you must call COMPLETEIOEDIT. You must supply the output values returned by AWAITIO[X] as the input to COMPLETEIOEDIT.
tag input INT(32):value supplies the value of tag returned by AWAITIO[X], which is the application-defined tag that was stored by the system when the I/O operation was initiated. Returned Value INT -1 if filenum designates a file being managed by IOEdit; 0 otherwise. Related Programming Manual For programming information about the COMPLETEIOEDIT procedure, see the Guardian Programmer's Guide.
COMPRESSEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The COMPRESSEDIT procedure copies a specified EDIT file to a new EDIT file that it creates. It fills each block in the new file as much as possible to minimize the number of disk pages used. It then purges the old file and renames the new file to have the name of the old file. The lines in the new file are renumbered if so requested.
start input INT(32):value specifies 1000 times the line number of the first line of the new file. You supply this parameter when you want the lines in the new file to be renumbered. If you omit start, renumbering still occurs if increment is present, in which case the value of increment is used for start. The possible EDIT line numbers are 0, 0.001, 0.002, ... 99999.999.
COMPUTEJULIANDAYNO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The COMPUTEJULIANDAYNO procedure converts a Gregorian calendar date on or after January 1, 0001, to a Julian day number. The Julian calendar is the integral number of days since January 1, 4713 B.C. The formal definition of the Julian day states that it starts at 12:00 (noon), Greenwich mean time (GMT).
error-mask output INT:ref:1 is a bit array in which the first three bits correspond (bit by bit) to year, month, and day: <0> Year <1> Month <2> Day If any one of these bits contains a 1, there is an error. If more than one bit is set, then the combination of elements is bad; which element is actually in error is unknown. For example, 01100000 00000000 is returned for April 31, in which case it is unknown whether April is in error or 31.
COMPUTETIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The COMPUTETIMESTAMP procedure converts a Gregorian (common civil calendar) date and time into a 64-bit Julian timestamp.
errormask output INT:ref:1 is a bit array that indicates any error in the date-n-time parameter. The errormask parameter checks each element of date-n-time for validity. If errormask is omitted, date-n-time is not checked. An error is indicated if any of these bits contains a 1.
CONFIG_GETINFO_BYLDEV_ Procedure CONFIG_GETINFO_BYNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for common-info Structure Definitions for specificinfo Considerations Summary The CONFIG_GETINFO_BYLDEV_ and the CONFIG_GETINFO_BYNAME_ procedures obtain the logical and physical attributes of a device. To specify the device by logical device number, use the CONFIG_GETINFO_BYLDEV_ procedure.
Syntax for TAL Programmers error := CONFIG_GETINFO_BYLDEV_ ( ldevnum ,common-info ,common-info-maxlen ,common-info-len ,specific-info:specific-info-maxlen ,specific-info-len ,timeout ,error-detail ); error := CONFIG_GETINFO_BYNAME_ ( devname:length ,common-info ,common-info-maxlen ,common-info-len ,specific-info:specific-info-maxlen ,specific-info-len ,timeout ,error-detail ); ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! i o i o o:i o i o i o i o o:i o i o Parameters ldevnum (CONFIG_GETINFO_BYLDEV_ only) input INT
specific-info:specific-info-maxlen output:input STRING .EXT:ref:*, INT:value if present and if specific-info-maxlen is not 0, points to a buffer that returns a set of physical device attributes obtained from the I/O subsystem that supports the specified device. The attribute values are returned in a structure that is defined by the I/O subsystem. See Structure Definitions for specificinfo (page 191) for a detailed description of the structure and values of this buffer.
Structure Definitions for common-info The common-info parameter points to a buffer that returns a set of logical attributes for a specified device. In the TAL ZSYSTAL file, the structure of the buffer that the common-info parameter points to is defined below.
In the C zsysc file, the structure of the buffer that the common-info parameter points to is defined below.
Z^NSK^DEVICENAME is the local name (that is, a name that does not include a node name) of the device whose attributes are being returned. This name has no qualifiers. Z^NSK^NODENAME returns the node name, and Z^QUALIFIER1 and Z^QUALIFIER2 return any qualifiers. Z^QUALIFIER1 is the first qualifier name subordinate to the device name returned in Z^NSK^DEVICENAME. For example, #Q1 is the first qualifier of the terminal process named $TERM.#Q1.Q2.
Z^SUBSYS^MANAGER is the name of the Guardian subsystem manager process. Z^PRIMARY^PHANDLE is the process handle of the primary I/O subsystem that owns the device. Z^BACKUP^PHANDLE is the process handle of the backup I/O subsystem that owns the device. Z^RESERVED^1 is reserved. Structure Definitions for specificinfo The specificinfo parameter contains information passed back from the subsystem called by CONFIG_GETINFO_BYNAME (and the other CONFIG_GETINFO procedures).
FIXED FIXED END; FIXED END; SCSILUN; SCSITARGET; PORT^NAME[0:3]; /*New field*/ The structure for tape devices is defined in TAL in file ZSTOTAL as follows: STRUCT SCSI^TAPE^DEVICE^INFO^DEF (*) FIELDALIGN (SHARED2); BEGIN STRUCT SPECIFIC^HDR; BEGIN INT VERSION; INT MAX^NUM^PATHS; INT PRIMARY^SUBTYPE; INT MIRROR^SUBTYPE; END; STRUCT PATH^INFO; BEGIN STRUCT STANDARD; BEGIN INT CONFIGURED; INT INUSE; INT STATE; INT RESERVED; INT(32) GROUP; INT(32) MODULE; INT(32) SLOT; INT(32) SUBDEVNUM; INT(32) FABRIC; FILLE
MIRROR_SUBTYPE Subtype of the magnetic disk located on the mirror volume. For more information about device subtypes, see Appendix A: Device Types and Subtypes. AUDITED (For magnetic disk and SCSI-IOP devices only.) This volume is currently audited for TMF. DEMOUNTABLE (For magnetic disk and SCSI-IOP devices only.) Always 1. The volume can be always be removed. RESERVE1 (For magnetic disk and SCSI-IOP devices only.) (Not used.) FLAGS (For magnetic disk and SCSI-IOP devices only.
MODULE A set of components that shares a hardware interconnection. A module is a subset of a group. It is contained in a system enclosure, and contains one or more slots. In a NonStop S-series server, there is exactly one module in a group. The valid range is from 1 through 99. SLOT A physical, labeled space in a module in which a CRU can be installed. The valid range is from 1 through 999. SUBDEVNUM The subtype of the device.
This structure definition can be found in the TAL ZWANTAL file. An equivalent C definition is in the zwanc file. Both files are found in $SYSTEM.ZSPIDEF.
Z^IPADDRESS is the IP address that is currently being used to access the SWAN. Considerations • It is possible for CONFIG_GETINFO_BYLDEV_ to return an error value of 0D (information successfully returned) while the I/O subsystem reports an error in the Z^LOGICAL^STATUS field of the returned buffer. In that case, the error value of 0D indicates that communication with the I/O subsystem was successful, while the I/O subsystem logical status value reflects the status of the I/O subsystem.
CONFIG_GETINFO_BYLDEV2_ Procedure CONFIG_GETINFO_BYNAME2_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for common-info Considerations Summary The CONFIG_GETINFO_BYLDEV2_ and CONFIG_GETINFO_BYNAME2_ procedures obtain the logical and physical attributes of a device. To specify the device by logical device number, use the CONFIG_GETINFO_BYLDEV2_ procedure. To specify the device by name, use the CONFIG_GETINFO_BYNAME2_ procedure.
Syntax for TAL Programmers error := CONFIG_GETINFO_BYLDEV2_ ( ldevnum ,common-info ,common-maxlen ,common-len ,specific-info:specific-maxlen ,specific-len ,timeout ,error-detail ); ! ! ! ! ! ! ! ! i o i o o:i o i o error := CONFIG_GETINFO_BYNAME2_ ( devname:length ,common-info ,common-maxlen ,common-len ,specific-info:specific-maxlen ,specific-len ,timeout ,error-detail ); ! ! ! ! ! ! ! ! i o i o o:i o i o Parameters ldevnum (CONFIG_GETINFO_BYLDEV2_ only) input INT(32):value specifies the logical devi
specific-info:specific-maxlen output:input STRING .EXT:ref:1, INT:value specifies an area where the device-specific information will be returned. If specific-info is zero or if specific-maxlen is zero, then no device-specific data is returned. Each device type or subtype might return a different set of data. See Structure Definitions for specificinfo (page 191) for a detailed description of the structure and values of this buffer.
Structure Definitions for common-info The common-info parameter points to a buffer that returns a set of logical attributes for a specified device. In the TAL ZSYSTAL file, the structure of the buffer that the common-info parameter points to is defined as follows.
In the C zsysc file, the structure of the buffer that the common-info parameter points to is defined as follows.
Z^LDEV^NUMBER is the logical device number of the device whose attributes are being returned. The logical device number could be set to -1. The logical device number of a device can change whenever a device is configured or the system is loaded. Some I/O subsystems do not have a logical device number. Z^DEVICE^RECORD^SIZE is the record size of the device. Z^DEVICE^TYPE is the type of the device. See Appendix A: Device Types and Subtypes for a list of device types.
Z^DEVNAME^OFF is the offset of Z^DEVNAME^DATA from beginning of the common-info parameter. Z^DEVNAME^LEN is the length of the device name in bytes. The maximum length is 64. Z^DEVNAME^DATA is the full device name. Considerations • It is possible for CONFIG_GETINFO_BYLDEV2_ to return an error value of 0D (information successfully returned) while the I/O subsystem reports an error in the Z^LOGICAL^STATUS field of the returned buffer.
CONTIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The CONTIME procedure converts a 48-bit timestamp to a date and time in integer form.
t0, t1, t2 input INT:value:3 is an array that must correspond to the 48 bits of a timestamp for the results of CONTIME to have any meaning (t0 is the most significant word; t2 is the least significant): t0 Most significant word, interval clock t1 Interval clock t2 Least significant word, interval clock Considerations • A 48-bit timestamp is a quantity equal to the number of 10-millisecond units since 00:00, 31 December 1974. The 48-bit timestamp always represents local civil time.
CONTROL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Operations Considerations Related Programming Manuals Summary The CONTROL procedure is used to perform device-dependent I/O operations. NOTE: The CONTROL procedure performs the same operation as the FILE_CONTROL64_ Procedure (page 379), which is recommended for new code. Key differences in FILE_CONTROL64_ are: • The tag parameter is 64 bits wide.
operation input INT:value defines the operation to be performed. (See Operations (page 207) for the list of available operations.) param input INT:value is the value of the operation to be performed. (See Operations for more information.) tag input INT(32):value applies to nowait I/O only. The tag parameter is a value you define uniquely identifying the operation associated with this CONTROL call. NOTE: The system stores the tag value until the I/O operation completes.
Table 10 CONTROL Operation 1 (continued) Description Subtype Description of 6 skip to VFU channel 6 (next one-fourth page) 7 skip to VFU channel 7 (next one-sixth page) 8 skip to VFU channel 8 (user-defined) 9 skip to VFU channel 9 (user-defined) 10 skip to VFU channel 10 (user-defined) 11 skip to VFU channel 11 (user-defined) 16–31 skip - 16 lines Line Printer 7 0 select VFC channel 1 (top of form) 1 select to VFC channel 2 (bottom of form) 2 skip to VFU channel 3 (sing
Table 11 CONTROL Operations 2 Through 27 Operation Description Description of 2 Write end of file on unstructured disk or magnetic tape (if disk, None write access is required). A write end of file (EOF) to an unstructured disk file sets EOF to point to the relative byte address indicated by the next-record pointer and writes the new EOF setting in the file label on disk. If this new EOF setting is out of bounds, EOF is set to the last possible position.
Table 11 CONTROL Operations 2 Through 27 (continued) Operation Description Description of 24 Magnetic tape, force end-of-volume (EOV). Next volume in set None is requested and current volume is unloaded. Valid only for ANSI or IBM label tape. 26 Requests immediate completion of all outstanding I/O requests None without loss of data by the recipient of the CONTROL 26 request. 27 Wait for DP2 disk file write. This operation is not supported for queue files.
NOTE: CONTROL 2 is valid only for unstructured files or structured files opened for unstructured access. For XP-based files, using CONTROL 2 to move the EOF will involve more CPU cycles. Writing the application data to the file and letting the disk process move the EOF as the data is written to the file, and removing the CONTROL 2 operations from the application code will improve the performance.
CONTROLBUF Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Messages Summary The CONTROLBUF procedure is used to perform device-dependent I/O operations requiring a data buffer. NOTE: The CONTROLBUF procedure performs the same operation as the FILE_CONTROLBUF64_ Procedure (page 382), which is recommended for new code. Key differences in FILE_CONTROLBUF64_ are: • The pointer and tag parameters are 64 bits wide.
Parameters filenum input INT:value is the number of an open file. It identifies the file on which the CONTROLBUF procedure performs an I/O operation. operation input INT:value defines the operation to be performed. (See Table 10: CONTROL Operation 1 (page 207) and Table 11: CONTROL Operations 2 Through 27 (page 209) for the list of available operations.
Considerations • Nowait and CONTROLBUF The CONTROLBUF procedure must complete with a call to the AWAITIO procedure when used with a file opened nowait. • Wait and count-transferred If a waited CONTROLBUF is executed, the count-transferred parameter indicates the number of bytes actually transferred. • Nowait and count-transferred If a nowait CONTROLBUF is executed, count-transferred has no meaning and can be omitted.
CONTROLMESSAGESYSTEM Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The CONTROLMESSAGESYSTEM procedure controls the maximum number of receive and send messages used by a process.
action code value Action Taken 2 N/A Beginning in the D-series RVU, this action code of the operating system is obsolete. 3 N/A Beginning in the D-series RVU, this action code of the operating system is obsolete. 1 For systems running G06.29 and later G-series RVUs. 2 For systems running H06.06 and later H-series RVUs or any J-series RVU. Returned Value INT:ref:1 Error code: 0 Success, no error. 2 Bad actioncode. 21 Bad value. 29 Missing parameter.
CONVERTASCIIEBCDIC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary The CONVERTASCIIEBCDIC procedure translates the 256 EBCDIC encodings to and from the 256 eight-bit ASCII encodings. For more information, see Appendix K: Character Set Translation.
CONVERTPROCESSNAME Procedure (Superseded by FILENAME_RESOLVE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CONVERTPROCESSNAME procedure converts a process name from local to network form. Syntax for C Programmers This procedure does not have a C syntax, because it is superseded and should not be used for new development.
CONVERTPROCESSTIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Related Programming Manual Summary The CONVERTPROCESSTIME procedure is used to convert the quad microsecond process time returned by the PROCESSTIME, MYPROCESSTIME, or PROCESSINFO procedure into hours, minutes, seconds, milliseconds, and microseconds. The maximum time that this procedure can convert is 3.7 years (the amount of time that can be represented using the output parameters).
minutes output INT:ref:1 is the minutes portion of the value of process-time specified. seconds output INT:ref:1 is the seconds portion of the value of process-time specified. milliseconds output INT:ref:1 is the milliseconds portion of the value of process-time specified. microseconds output INT:ref:1 is the microseconds portion of the value of process-time specified. Condition Code Settings < (CCL) returns if process-time represents a quantity greater than 3.7 years.
CONVERTTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The CONVERTTIMESTAMP procedure converts a Greenwich mean time (GMT) timestamp to or from a local-time-based timestamp within any accessible node in the network. A local timestamp can be in local standard time (LST), which does not include daylight saving time (DST), or in local civil time (LCT), which does include DST.
direction input INT:value indicates what time form or timestamp to return. You can specify one of these values for direction: 0 GMT to LCT 1 GMT to LST 2 LCT to GMT 3 LST to GMT If direction is omitted, 0 is used. If direction is out of range, a value of -3 is returned in error. node input INT:value is the number of the node at which the conversion is to take place. If the node parameter is omitted or -1, the caller's node is used.
• LCT timestamps LCT timestamps should be used with caution because of the negative adjustment that DST systems dictate. Timestamp base conversion (for example, LCT) is provided by the operating system. • A 64-bit Julian timestamp is based on the Julian date. It is a quantity equal to the number of microseconds since January 1, 4713 B.C., 12:00 (noon) Greenwich mean time (Julian proleptic calendar). This timestamp can represent either Greenwich mean time, local standard time, or local civil time.
• Use (or Avoidance) of Local Civil Time It is hard to avoid all problems with conversion between local civil time (which includes the effect of daylight saving time) and GMT or local standard time. Because civil time is convenient for people to use for comparison with local clocks, some use of civil time is expected. Accordingly, the best strategy might be to store all timestamps in GMT, and then to convert the GMT timestamps to civil time, when desired, before displaying them.
CPU_GETINFOLIST_ Procedure Use the PROCESSOR_GETINFOLIST_ Procedure (page 1156) instead of CPU_GETINFOLIST_. Calls to PROCESSOR_GETINFOLIST_ are identical in their format and values to those for CPU_GETINFOLIST_.
CPUTIMES Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Summary The CPUTIMES procedure returns the length of time (in microseconds) that a given processor has spent in these states since it was loaded or reloaded: • Process busy • Interrupt busy • Idle These times reflect the amount of time spent by the processor (from the last system load or reload) in a process environment, an interrupt environment, and the idle state.
total-time output FIXED:ref:1 returns the elapsed time, in microseconds as measured by the processor clock, since the processor was loaded or reloaded. cpu-process-busy output FIXED:ref:1 returns the length of time, in microseconds as measured by the processor clock, that the processor has been busy executing processes since it was loaded or reloaded.
CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Safeguard Considerations OSS Considerations Example Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CREATE procedure is used to define a new structured or unstructured disk file.
Permanent Disk File [0:3] $volname (blank-fill) or \sysnum volname (blank-fill) [4:7] subvol-name (blank-fill) [8:11] file-id (blank-fill) Temporary Disk File [0:3] $volname (blank-fill) or \sysnum volname (blank-fill) [4:11] blank-fill When CREATE finishes, a temporary file name is returned in file-name[4:7]. The temporary file can then be opened by passing file-name to OPEN. primary-extentsize input INT:value is the size of the primary extent in pages (one page is 2048 bytes).
number (whole word boundary); thus, 3 rounds up to 4, and so forth. ODDUNSTR prevents this rounding, so that reading, writing, or positioning occurs at the exact RBA specified. (See Considerations (page 235).) <12> Specifies data compression for key-sequenced files. (For additional information, see the Enscribe Programmer's Guide.
key-sequenced-params input INT:ref:3 is a three-word array containing parameters that describe this file. This parameter is required for key-sequenced files, omit the parameter for other file types. The array has this form: Word[0] key-len Word[1] key-offset Word[2] index-block-len where: key-len is the length, in bytes, of the record's primary-key field. In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the maximum key length for format 2 key-sequenced files is 2048.
nf-alt-files is a one-byte value that specifies the number of alternate-key files for this primary file. nk-alt-keys isa one-byte value that specifies the number of alternate-key fields in this primary file. Key Description The key description for key k consists of four words, each of the form: 0 8 [k * 4 + 1] key-specifier [k * 4 + 2] key-attributes [k * 4 + 3] null-value [k * 4 + 4] key-filenum key-len where: key-specifier is a two-byte value that uniquely identifies this alternate-key field.
key-len specifies the length, in bytes, of the alternate-key field: • If the alternate keys are unique, the maximum alternate key length is 253 bytes. • If primary-key-ordered duplicate alternate keys are allowed, the maximum alternate key length is (253 – primary-key length). • If insertion-ordered duplicate alternate keys are allowed, the maximum alternate key length is (245 – primary-key length).
This sequence must be included in the partition-parameters array for key-sequenced files, but it can be omitted for other file types: [1] partial-keylen partial-keyvalue for partition 1 : partial-keyvalue for partition n num-of-extra-partitions is the number of extra volumes (other than the one specified in the file-name parameter) on which the file resides. The maximum value is 15 for legacy key-sequenced files, 63 for enhanced key-sequenced files in RVUs between H06.22/J06.11 and H06.28/J06.
maximum-extents input INT:value is the maximum number of extents to be allocated for the file. The minimum and default value is 16. See Considerations for the upper limit on this value. unstructured-buffer-size input INT:value declares the internal buffer size to be used for an unstructured file. Must be 512, 1024, 2048, or 4096. The default is 4096 bytes. open-defaults input INT:value specifies the file label default values for various open attributes. <0> <1> <2> <3> 0 Verify writes off (default).
- 4096 bytes (approximately four gigabytes), or a partition size greater than 2**31 bytes (two gigabytes). • For unstructured files on a disk device other than a legacy device with 514-byte sectors3, both primary-extent-size and secondary-extent-size must be divisible by 14.
The relative position of an alternate-key record within a set of duplicates may change if a nonrecoverable error occurs during a WRITEUPDATE of the primary record. There is a performance penalty for using insertion-ordered duplicate alternate keys. Updates and deletes of alternate-key fields force the disk process to sequentially search the set of alternate-key records having the same altkeyvalue until a match is found on the primarykey-value portion of the key.
Safeguard Considerations For information on files protected by Safeguard, see the Safeguard Reference Manual. OSS Considerations This procedure operates only on Guardian objects. If an OSS file is specified, error 1163 is returned. Example CALL CREATE ( DISK^FNAME , PRI^EXT , FILE^CODE , SEC^EXT , FILE^TYPE , REC^LEN , DATA^BLK^LEN , KEY^PARAMS ); Related Programming Manual For programming information about the CREATE procedure, see the Enscribe Programmer's Guide.
CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CREATEPROCESSNAME procedure returns a unique process name suitable for passing to the NEWPROCESS and NEWPROCESSNOWAIT procedures.
Considerations • Process names and CREATEPROCESSNAME You use names created by CREATEPROCESSNAME when the process must be named, but the name of that process does not need to be predefined, that is, known by any other process or process pair. NOTE: Calling CREATEPROCESSNAME does not create a process or enter the process name into the DCT.
CREATEREMOTENAME Procedure (Superseded by PROCESSNAME_CREATE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CREATEREMOTENAME procedure supplies a process name that is unique for the specified system in a network.
Condition Code Settings < (CCL) indicates that the remote destination control table (DCT) could not be accessed or the address passed for name is out of bounds. = (CCE) indicates that CREATEREMOTENAME was successful. > (CCG) indicates there were no unused names in the reserved name space ($Xname, $Yname, and $Zname, where name is 1 through 4 alphanumeric characters) for CREATEREMOTENAME to use. Considerations • Remote process name characteristics CREATEREMOTENAME creates a process name in local form.
CREATORACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Example Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The CREATORACCESSID procedure is used to obtain the creator access ID (CAID) of the process that created the calling process.
Both the PAID and the CAID are returned from the PROCESS_GETINFO[LIST]_ procedures. See the Guardian Programmer's Guide for information about process access IDs. Example CREATOR^ID := CREATORACCESSID; Related Programming Manual For more information about the creator accessor ID (CAID), see the Guardian User's Guide.
CRTPID_TO_PROCESSHANDLE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The CRTPID_TO_PROCESSHANDLE_ procedure converts a process ID (CRTPID) to the corresponding process handle. For information about process IDs and process handles, see Appendix D: File Names and Process Identifiers.
pair-flag output INT .EXT:ref:1 returns a value of 1 if • cpu and pin value in process-id is set to -1 • cpu and pin value in process-id is set to blanks (" ") It returns a value of 0 otherwise. node-number input INT(32):value if present and not equal to -1D, and if process-id is not in network form, identifies the node on which the process identified by process-id resides. If omitted or equal to -1D, the caller's node is assumed.
CURRENTSPACE Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The CURRENTSPACE procedure returns the ENV register (as saved in the stack marker) and a string (in ASCII) containing the space ID of the caller.
Returned Value INT The calling procedure's space ID in the stack-marker ENV register format: ENV.<4> ENV.<7> ENV.<11:15> ! library bit ! system code bit ! space ID bits For more information about space identifiers and the details of these bits, see the system description manual appropriate for your system. Related Programming Manual For information about the CURRENTSPACE procedure, see the appropriate System Description Manual for your system.
4 Guardian Procedure Calls (D-E) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letters D through E. Table 12 lists all the procedures in this section.
Table 12 Procedures Beginning With the Letters D Through E (continued) DST_TRANSITION_MODIFY_ Procedure EDITREAD Procedure EDITREADINIT Procedure ERRNO_GET_ Procedure EXTENDEDIT Procedure 250 Guardian Procedure Calls (D-E)
DAYOFWEEK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Example Summary The DAYOFWEEK procedure takes a 32-bit Julian day number and returns the corresponding day of the week.
DEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The DEALLOCATESEGMENT procedure deallocates an extended data segment when it is no longer needed by the calling process.
Condition Code Settings < (CCL) Segment not deallocated—an invalid segment ID was supplied or the specified segment is currently in use by the operating system; for example, an outstanding nowait I/O operation using a buffer in the segment has not been completed by a call to AWAITIOX. = (CCE) Segment deallocated. > (CCG) Segment deallocated, but an I/O error occurred writing dirty pages to the segment's permanent swap file. Considerations • flags parameter The flags..
DEBUG Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Considerations OSS Considerations Related Programming Manual Summary The DEBUG procedure invokes the debugging facility on the calling process. The operating system provides a debugging facility that responds to debug events by passing control to one of two debugging utilities: Debug or the Inspect debugger. Debug is a low-level debugger.
• • You can use the Inspect debugger by setting the Inspect attribute associated with a process.
DEBUGPROCESS Procedure (Superseded by PROCESS_DEBUG_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations OSS Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The DEBUGPROCESS procedure invokes the debugging facility on a process.
error output INT:ref:1 returns a file-system error number indicating the outcome of the process debug attempt. Possible values include these: 0 No error. 11 The specified process does not exist. 13 Invalid name. This error can occur when the supplied process ID is improperly formed. 14 The supplied process ID references an LDEV that does not exist. 18 The specified system is not known. 22 Parameter or buffer out of bounds. 29 Missing parameter. 48 Security violation.
To debug an OSS process, one of these must be true: • The calling process must have appropriate privilege; that is, it must be locally authenticated as the super ID on the system where the target process is executing. • All these apply: ◦ The caller's effective user ID is the same as the saved user ID of the target process.
DEFINEADD Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DEFINEADD procedure adds a DEFINE to the calling process' context using the attributes in the working set. It can be used to replace an existing DEFINE with the attributes in the working set.
Returned Value INT Outcome of the call: 0 Success. 2049 A syntax error occurred in name. 2050 Define already exists. 2051 Define does not exist. 2052 Unable to obtain file-system buffer space. 2053 Unable to obtain physical memory. 2054 Bounds error in define-name. 2057 Working set is incomplete, a required attribute is missing. 2058 Working set is inconsistent. Two or more attributes have conflicting values. The checknum parameter identifies the consistency check that failed.
DEFINEDELETE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Related Programming Manual Summary The DEFINEDELETE procedure allows the caller to delete a DEFINE from the calling process' context. Syntax for C Programmers #include short DEFINEDELETE ( const char *define-name ); Syntax for TAL Programmers error := DEFINEDELETE ( define-name ); ! i Parameter define-name input STRING .
Considerations • If an error occurs, the DEFINE is not deleted. • The context-changes count is incremented each time DEFINEDELETE is invoked and a consequent change to the process' context occurs. The count is incremented by one even if more than one DEFINE is deleted. Example STRING .EXT define^name[0:23]; . . define^name ':=' ["=mytape error := DEFINEDELETE ( define^name ); IF error <> DEOK THEN ...
DEFINEDELETEALL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Considerations Related Programming Manual Summary The DEFINEDELETEALL procedure allows the caller to delete all DEFINEs from the calling process' context. Syntax for C Programmers #include short DEFINEDELETEALL ( void ); Syntax for TAL Programmers CALL DEFINEDELETEALL; Considerations • If an error occurs, the DEFINE is not deleted.
DEFINEINFO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The DEFINEINFO procedure returns selected information about a DEFINE.
attribute-name output STRING .EXT:ref:16 is the name of an attribute; the specific attribute that is returned depends on the CLASS attribute of the DEFINE. The name is left-justified and blank-filled. These attribute names are returned: This attribute… Is returned for this CLASS attribute of the DEFINE FILE CLASS MAP LOC CLASS SPOOL SCRATCH CLASS SORT and CLASS SUBSORT SUBVOL CLASS CATALOG SUBVOL0 CLASS SEARCH VOLUME CLASS TAPE, CLASS TAPECATALOG and CLASS DEFAULTS value-buf output STRING .
Considerations The DEFINEINFO procedure is designed to support the short form of the command interpreter INFO command. Example STRING .EXT define^name[0:23]; STRING .EXT class^name[0:15]; STRING .EXT attr^name[0:15]; STRING .EXT value^buf[0:n]; INT value^buf^len; INT value^len; . . define^name ':=' ["=mytape "]; value^buf^len := n; error := DEFINEINFO( define^name, class^name, attr^name, value^buf, value^buf^len, value^len ); IF error <> DEOK THEN ...
DEFINELIST Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Related Programming Manual Summary The DEFINELIST procedure is used only when the application process is acting as a supervisor or tributary station in a centralized multipoint configuration. • Within a supervisor station, DEFINELIST specifies the station addresses of each tributary station that the application process wishes to communicate with.
address-list input INT:ref:* is the name of an integer array containing either: • Polling addresses and selection addresses (for a description of this array, see the Envoy Byte-Oriented Protocols Reference Manual) • one or more station addresses (for a description of this array, see the EnvoyACP/XF Reference Manual ) address-size input INT:value specifies the size, in words, of an entry in the station-list array. Note that the entry size varies somewhat from one protocol to another.
Considerations Call DEFINELIST after the call to FILE_OPEN_ or OPEN but before the first call to READ or WRITE. Related Programming Manual For programming information about the DEFINELIST procedure, see the data communication manuals.
DEFINEMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DEFINEMODE procedure allows the caller to control the use of DEFINEs (the DEFINE mode of the process). See the Guardian Programmer's Guide for details on the DEFINE mode and its effects.
Considerations • The new-value and old-value parameters correspond to the DEFMODE attribute of a process: ◦ DEFMODE OFF corresponds to value 0. ◦ DEFMODE ON corresponds to value 1. • If new-value is not supplied, the call to DEFINEMODE does not change the current value of DEFINE mode.
DEFINENEXTNAME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The DEFINENEXTNAME procedure returns the name of the DEFINE that follows the specified DEFINE (in ASCII order). Syntax for C Programmers #include short DEFINENEXTNAME ( char *define-name ); Syntax for TAL Programmers error := DEFINENEXTNAME ( define-name ); ! i,o Parameter define-name input, output STRING .
Considerations • To obtain the name of the very first DEFINE in the process context, define-name must be blanks. • On output, define-name is either a valid existing DEFINE (on success) or is unchanged (on failure). Example In the following example, DEFINENEXTNAME returns "=my^output", which directly follows "=my^input" in ASCII order. These DEFINEs were created previously. STRING .file^name [0:36]; file^name ':=' ["=my^input"]; error := DEFINENEXTNAME( file^name ); IF error <> DEOK THEN ...
DEFINEPOOL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DEFINEPOOL procedure designates a portion of a user's stack, global data or a data segment for use as a pool. It initializes the pool for use with the GETPOOL, PUTPOOL and RESIZEPOOL procedures. NOTE: These procedures are supported for compatibility with previous software and should not be used for new development. The ...
pool input INT .EXT:ref:* specifies the address of the first word of the memory space to be used as the pool. An even-byte address must be specified. The address of the actual beginning of the pool might be adjusted for alignment. pool-size input INT(32):value specifies the size of the pool in bytes. This number must be a multiple of 4 bytes and cannot be less than 32 bytes or greater than 127.5 megabytes (133,693,440 bytes).
The program must release one entire block using PUTPOOL; it may not return part of a block or multiple blocks in one PUTPOOL call. Be careful to use only the currently reserved blocks of the pool, or the pool structure is corrupted and unpredictable results occur. If multiple pools are defined, do not return reserved blocks to the wrong pool. For debugging purposes, a special call to GETPOOL checks for pool consistency.
DEFINEREADATTR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The DEFINEREADATTR procedure allows the caller to obtain the current value of an attribute in a DEFINE in the calling process' context or in the working set. The value of a specific attribute can be read or all the attributes can be sequentially read. The value is returned in an ASCII string form suitable for display.
If cursor is present, then this is an output parameter. The name is left-justified and blank-filled on output. cursor input, output INT:ref:1 is a pointer to the attribute on input. On output, cursor points to the sequentially next attribute that is to be read. To read the first attribute, set the cursor to 0. To sequentially read all attributes, do not modify this parameter. If both attribute-name and cursor are present, then cursor is used to identify the attribute. value-buf output STRING .
info-word.<13> is set if this attribute was involved in an inconsistency at the last check. (For a list of DEFINE consistency check numbers, see the description of the checknum parameter for DEFINEADD Procedure (page 259).) Returned Value INT Outcome of the call: 0 Success. 2049 A syntax error occurred in name. 2051 DEFINE not found. 2052 An error occurred when placing PFS in use. 2054 Bounds error on parameter. 2055 Attribute not supported.
Example LITERAL define^vol^len=25; ! value buffer length STRING .EXT define^name [0:23]; STRING .EXT volume [0:15]; ! attribute name STRING .EXT volid [0:define^vol^len]; ! value buffer INT len^read := 0; ! len of external rep. . . define^name ':=' ["=mytape "]; volume ':=' ["volume "]; volid ':=' " " & volid[ 0 ] for define^vol^len; error := DEFINEREADATTR ( define^name, volume, , volid, define^vol^len, len^read ); IF error <> THEN ...
DEFINERESTORE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The DEFINERESTORE procedure uses a saved version of a DEFINE in the user's buffer to create an active DEFINE. If an active DEFINE of the same name already exists, it can optionally be replaced. The saved DEFINE can also be placed in the working set without its name.
If options is omitted, the default value of 0 is used; in other words, the saved DEFINE is added to the set of active DEFINEs. define-name output STRING .EXT:ref:24 if present, contains the name of the saved DEFINE added to the current context. The name is either the name of the DEFINE when it was saved or the name given the working set when it was saved. checknum output INT:ref:1 if present, and the DEFINE is inconsistent, contains the number of the consistency check that failed.
• DEFINEs saved by later RVUs of the operating system will be restorable only if the class of the DEFINE is supported on the earlier RVU and the attributes and their values are supported on the earlier RVU. • If DEFINERESTORE encounters error 2057, 2058, or 2059 (DEFINE invalid, incomplete, or inconsistent) while attempting to restore the saved DEFINE to the working attribute set, it still performs the restore. If it encounters any other errors, however, it leaves the working attribute set unchanged.
DEFINERESTOREWORK[2] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Related Programming Manual Summary The DEFINERESTOREWORK procedure restores the working set from the background set. The working set is the current set of attributes and their values. A background set is a scratchpad work area used when creating DEFINEs. The DEFINERESTOREWORK2 procedure allows a second background working set, saved by DEFINESAVEWORK2, to be restored.
DEFINESAVE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The DEFINESAVE procedure copies an active DEFINE or the current working attribute set into a user buffer. The saved DEFINE can later be made an active DEFINE or be placed into the working set by using DEFINERESTORE.
deflen output INT .EXT:ref:1 is the length of the saved DEFINE in bytes. option input INT:value indicates whether the working set or an active DEFINE is to be saved: <0:14> are reserved and must be 0. <15> 1 save the current working set and name it define-name. 0 save the active DEFINE named by define-name. If option is omitted, then the active DEFINE named by define-name is saved. Returned Value INT Outcome of the call: 0 Success. 2049 Syntax error in name. 2051 DEFINE not found.
• The working set can be saved if it is inconsistent, invalid, or incomplete. A warning is returned in error. • If the user's buffer is too small, error will contain 2076 and deflen will contain the buffer size required, in bytes. To reduce the possibility of getting error 2076, allocate a buffer of 4096 bytes. Related Programming Manual For programming information about the DEFINESAVE procedure, see the Guardian Programmer's Guide.
DEFINESAVEWORK[2] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Related Programming Manual Summary The DEFINESAVEWORK procedure saves the DEFINE working set in the background set. The DEFINESAVEWORK2 procedure allows a second background working set to be saved.
DEFINESETATTR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DEFINESETATTR procedure allows the caller to modify the value of an attribute in the working set. The value is supplied in ASCII string form. It is validated, converted into the internal representation, and established as the value for the attribute.
value-len input INT:value is the length (in bytes) of the array value. If -1, the value of the attribute is reset; the attribute is given a default value, if it has one, or the attribute is deleted. default-names input INT:ref:8 contains the default volume and subvolume names to be used to convert from the external representation of the value to an internal representation. [0:3] Default volume name. First two bytes can be "\sysnum," in which case "$" is omitted from volume name (blank-filled on right).
• attribute-name should not be declared as a P-relative array. In general, a reference parameter should not be declared as a P-relative array. • default-names should be supplied in certain cases. For more information, see Setting Attributes Using the DEFINESETATTR Procedure in the Guardian Programmer's Guide. Example STRING .EXT labelprocessing [0:15]; ! attribute name STRING .EXT value [0:15]; ! attribute value INT .default^names [0:7]; LITERAL value^len=6; ! attribute value length . .
DEFINESETLIKE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Related Programming Manual Summary The DEFINESETLIKE procedure can be used to initialize the working set with the attributes in an existing DEFINE. Syntax for C Programmers #include short DEFINESETLIKE ( const char *define-name ); Syntax for TAL Programmers error := DEFINESETLIKE ( define-name ); ! i Parameter define-name input STRING .
Considerations The existing attributes in the working set are deleted. They can be saved in the background set by calling DEFINESAVEWORK before calling this procedure. Related Programming Manual For programming information about the DEFINESETLIKE procedure, see the Guardian Programmer's Guide.
DEFINEVALIDATEWORK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Related Programming Manual Summary The DEFINEVALIDATEWORK procedure can be used to check the working set for consistency.
• DEFINEADD invokes this procedure before creating a DEFINE or replacing an existing DEFINE with the working set. • The command interpreter SHOW command invokes this procedure before calling DEFINEREADATTR. • DEFINEREADATTR can be used to obtain more information about the attributes in the working set that can be useful to determine why the working set is inconsistent, incomplete or both (invalid).
DELAY Procedure (Superseded by PROCESS_DELAY_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Example Summary The DELAY procedure permits a process to suspend itself for a timed interval.
Example CALL DELAY ( 1000D ); ! suspend for 10 seconds.
DELETEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The DELETEEDIT procedure deletes from an EDIT file all lines that have line numbers in a specified range. Upon completion, the current record number is set to the highest line number in the file that is lower than the deleted range, or to -1 if there is no such line.
last input INT(32):value specifies 1000 times the line number of the last line in the range of lines to be deleted. If a negative value is specified, the line number of the last line in the file is used. Returned Value INT A file-system error code that indicates the outcome of the call. Example In the following example, DELETEEDIT deletes lines 50 through 100 from the specified file: INT(32) first := 50000D; INT(32) last := 100000D; . .
DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series RVUs) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Device Attributes and Value Representations Considerations Example Related Programming Manual Summary NOTE: On G-series RVUs, this procedure is supported for compatibility with previous software and should not be used for new development. This procedure cannot obtain all of the physical attributes of a device.
Syntax for TAL Programmers error := DEVICE_GETINFOBYLDEV_ ( ldevnum ,[ logical-info ] ,[ logical-info-maxlen ] ,[ logical-info-len ] ,[ primary-info ] ,[ primary-info-maxlen ] ,[ primary-info-len ] ,[ backup-info ] ,[ backup-info-maxlen ] ,[ backup-info-len ] ,[ timeout ] ,[ options ] ,[ match-type ] ,[ devname:maxlen ] ,[ devname-len ] ,[ error-detail ] ); ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! i o i o o i o o i o i i i o:i o o Parameters ldevnum input INT(32):value specifies a logical device number that is us
logical-info-len output INT .EXT:ref:1 returns the actual length (in bytes) of the buffer pointed to by logical-info. This parameter must be present if logical-info is present. primary-info output INT .EXT:ref:* if present and if primary-info-maxlen is not 0, points to a buffer that returns a set of physical device attributes obtained from the primary I/O process that supports the specified device. The attribute values are returned in a contiguous array.
backup-info-len output INT .EXT:ref:1 returns the actual length (in bytes) of the buffer pointed to by backup-info. This parameter must be present if backup-info is present. timeout input INT(32):value specifies how many hundredths of a second the procedure should wait for a response from the I/O process. The maximum value is 2147483647. The default value is 6000D (one minute). A value of -1D causes the procedure to wait indefinitely. options input INT:value specifies options.
devname:maxlen output: input STRING .EXT:ref:*, INT:value if supplied and if maxlen is not 0, returns a local name (that is, a name that does not include a node name) designating the device. The returned name has no qualifiers. If the device does not have a name, a devname-len of 0 is returned. A devname in the form $logical-device-number is never returned. maxlen specifies the length (in bytes) of the string variable devname. devname-len output INT .
Attribute TAL Value Representation demountable UNSIGNED(1) has-subnames (12 bits of filler) UNSIGNED(1) The attributes returned in logical-info are defined as follows: • ldev is the logical device number of the device for which information has been obtained. On G-series RVUs, the logical device number of a device can change whenever a device is configured or the system is loaded. • primary-processor is the number of the processor in which the primary IOP that owns the device is running.
Attribute TAL Value Representation has-physical-devices UNSIGNED(1) is-primary (14 bits of filler) UNSIGNED(1) path 0 information: configured UNSIGNED(1) in-use (14 bits of filler) UNSIGNED(1) channel INT controller INT unit INT state INT path 1 information: configured UNSIGNED(1) in-use (14 bits of filler) UNSIGNED(1) channel INT controller INT unit INT state INT path 2 information: configured UNSIGNED(1) in-use (14 bits of filler) UNSIGNED(1) channel INT controller INT
• has-physical-devices is equal to 1 unless the logical device does not own a channel address. $TMP, $0, and $IPB are examples of logical devices that do not own channel addresses. • is-primary identifies the current primary process of the IOP pair. This bit should be set to 1 in only one of the physical information sets. • configured is equal to 1 if the path is known to the device. Devices such as terminals and tape drives have only one path configured; disks can have two or four paths configured.
It is possible for DEVICE_GETINFOBYLDEV_ to return an error value of 0 (information successfully returned) while the IOP reports an error in the status field. In that case, the error value of 0 indicates that communication with the IOP was successful, while the IOP status value reflects the validity of the returned information. • Searching logical devices To perform a search of logical devices, you must specify options.<15> = 1.
DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series RVUs) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary NOTE: On G-series RVUs, this procedure is supported for compatibility with previous software and should not be used for new development. This procedure cannot obtain all of the physical attributes of a device. For new development, call the CONFIG_GETINFO_BYNAME_ procedure.
Parameters devname:length input:input STRING .EXT:ref:*, INT:value specifies the name of the device for which information is requested. devname must be a local name (that is, it must not include a system name) and must have no qualifiers. A devname in the form $logical-device-number (for example, $23) is acceptable. devname must be exactly length bytes long. logical-info output INT .EXT:ref:* if present and if logical-info-maxlen is not 0, returns a set of logical attributes for the specified device.
primary-info-maxlen input INT:value specifies the length (in bytes) of the buffer pointed to by primary-info. If the buffer length is too short for the full set of device attributes, the procedure returns as many values as will fit in the buffer. This parameter must be present if primary-info is present. primary-info-len output INT .EXT:ref:1 returns the actual length (in bytes) of the buffer pointed to by primary-info. This parameter must be present if primary-info is present. backup-info output INT .
for some returned errors, contains additional information. See Returned Value. Returned Value INT Outcome of the call: 0 Information was successfully returned. 1 (reserved) 2 Parameter error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left. 3 Bounds error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left.
DEVICEINFO Procedure (Superseded by FILE_GETINFOBYNAME_ Procedure or FILE_GETINFOLISTBYNAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. DEVICEINFO cannot obtain information on devices that have a device type greater than 63. The DEVICEINFO procedure is used to obtain the device type and the physical record length of a file.
FILE_GETINFOLISTBYNAME_ procedure. For a list of the device types, see Appendix A: Device Types and Subtypes. physical-recordlen output INT:ref:1 returns the physical record length associated with the file. Physical record length is determined as follows: • nondisk devices physical-recordlen is the configured record length. • disk files physical-recordlen is the maximum possible transfer length. The transfer length is equal to the configured buffer size for the device (either 2048 or 4096 bytes).
DEVICEINFO2 Procedure (Superseded by FILE_GETINFOBYNAME_ Procedure or FILE_GETINFOLISTBYNAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. DEVICEINFO2 cannot obtain information on devices that have a device type greater than 63.
Device type <4:9> <10:15> Device subtype If the device type is greater than 63, bits <4:9> are set to 44. To obtain information on devices with a device type greater than 63, call either the FILE_GETINFOBYNAME_ or FILE_GETINFOLISTBYNAME_ procedure. For a list of the device types, see Appendix A: Device Types and Subtypes. physical-recordlen output INT:ref:1 returns the physical record length associated with the file: • nondisk devices physical-recordlen is the configured record length.
tag-or-timeout input INT(32):value is a parameter with two functions depending on the options you specify: • If options.<13> = 1, it is a value you define that helps identify one of several DEVICEINFO2 operations. The system stores this value until the operation completes, then returns it to the program in words 1 and 2 of a system message. See Considerations for more information. • If options.<14> = 1, it is the maximum amount of time, in hundreths-of-second units, to wait.
DISK_REFRESH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary NOTE: On G-series RVUs, this procedure is supported for compatibility with previous software and should not be used for new development; the function that it provides is no longer needed. The DISK_REFRESH_ procedure causes control information to be written to the specified disk volume.
Parameter name:length input:input STRING .EXT:ref:*, INT:value specifies the name of the disk volume (or a file on the disk volume) that is to have control information written out. If a disk file is specified, the operation is performed for the entire volume on which the file resides. The value of name must be exactly length bytes long and must be a valid file (or volume) name or DEFINE name.
DISKINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The DISKINFO procedure obtains information about disk volumes. Syntax for C Programmers This procedure does not have a C syntax, because it is superseded and should not be used for new development.
numfrag output INT(32) .EXT:ref:1 is the number of individual free space fragments. biggest output INT(32) .EXT:ref:1 is the size, in pages, of the largest free space fragment. drivekinds output STRING .EXT:ref:16 identifies the kinds of drives on which the volume is mounted.
DNUMIN[64_] Procedures Summary Syntax for C Programmers Syntax for pTAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DNUMIN[64_] procedures convert the ASCII characters used to represent a number into the signed 32-bit integer value for that number. The DNUMIN procedure is only supported for 32-bit processes. 64-bit processes should use the DNUMIN64_ procedure.
Parameters DNUMIN64_ has the same parameters as DNUMIN. The only difference is the data type of the parameters. Pointers are explicitly 64-bits wide in DNUMIN64_. ascii-number input STRING .EXT:ref:* (for DNUMIN) STRING .EXT64:ref:* (for DNUMIN64_) is an array containing the number to be converted to signed double word integer form.
flags input INT:value can be used to alter the number format accepted by DNUMIN as follows: <0:12> Must be 0. <13> Disallow preceding sign (+/-). <14> Disallow prefixes (%, #, and so on). <15> Permit two-word number of the form integer1.integer2 where each unsigned integer must fit in a 16-bit word. If not supplied, flags defaults to zero.
DNUMOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The DNUMOUT procedure converts unsigned double word integer values to their ASCII equivalents. The result is returned right-justified in an array. If necessary, leading zeros are zero-filled (the default) or blank-filled.
unsigned-doubleword input INT(32):value is the unsigned double-word integer to be converted. base input INT:value is the number base for the resulting conversion. Any number in the range 2 through 36 is valid. width input INT:value is the maximum number of characters permitted in ascii-result. The output value will be right-justified to the specified width; characters may be truncated on the left side.
DST_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The DST_GETINFO_ procedure, for G05.00 and later G-series RVUs, provides the information about the DST entry that is in effect at time keygmt.
Example #include short error; long long keyGMT; zsys_ddl_dst_entry_def dstentry; dstentry.
DST_TRANSITION_ADD_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Structure Definitions for dstentry DST_... Procedure Errors Considerations Example Summary The DST_TRANSITION_ADD_ procedure, for G05.00 and later G-series RVUs, allows a super-group user (255,n) to add an entry to the daylight-saving-time (DST) transition table. This operation is allowed only when the DAYLIGHT_SAVING_TIME option in the system is configured to the TABLE option.
Structure Definitions for dstentry The dstentry parameter specifies the attributes of the new process. In the TAL ZSYSTAL file, the structure for the dstentry parameter is defined as: STRUCT ZSYS^DDL^DST^ENTRY^DEF (*) ?IF PTAL FIELDALIGN (SHARED2) ?ENDIF PTAL BEGIN FIXED FIXED INT INT INT(32) Z^LOWGMT; Z^HIGHGMT; Z^OFFSET; Z^VERSION; Z^FILLER; END; Z^LOWGMT identifies the lower limit of the interval in Greenwich Mean Time (GMT). Z^HIGHGMT identifies the higher limit of the interval in GMT.
Table 13 Error Summary for DST_... Procedures (continued) Error Literal Description 8 ZSYS^VAL^DST^BOUNDS^ERROR An attempt was made to use time values outside the supported range. The supported range is 1/ 1/ 1 0:00:00.000000 through 10000/12/31 23:59:59.999999 GMT. 9 ZSYS^VAL^DST^RANGE^LOW The specified keygmt value was less than the lowgmt value of the first DST interval with nonzero offset. This error is returned by the DST_GETINFO_ procedure.
DST_TRANSITION_DELETE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The DST_TRANSITION_DELETE_ procedure, for G05.00 and later G-series RVUs, allows a super-group user (255,n) to delete an existing entry from the daylight saving time (DST) transition table. This operation is allowed only when the DAYLIGHT_SAVING_TIME option in the system is configured to the TABLE option.
Example #include zsys_ddl_dst_entry_def dstentry; short error; long long timeStampLow, timeStampHigh; dstentry.z_lowgmt = timeStampLow; dstentry.z_highgmt = timeStampHigh; dstentry.z_offset = 3600; /* seconds */ dstentry.
DST_TRANSITION_MODIFY_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The DST_TRANSITION_MODIFY_ procedure, for G05.00 and later G-series RVUs, allows a super-group user (255,n) to modify an entry in the daylight-saving-time (DST) transition table. This operation is allowed only when the DAYLIGHT_SAVING_TIME option in the system is configured to the TABLE option.
Example #include zsys_ddl_dst_entry_def olddstentry, newdstentry; short error; long long oldTimeStampLow, oldTimeStampHigh; long long newTimeStampLow, newTimeStampHigh; olddstentry.z_lowgmt = oldTimeStampLow; olddstentry.z_highgmt = oldTimeStampHigh; olddstentry.z_offset = 3600; /* seconds */ olddstentry.z_version = ZSYS_VAL_DST_VERSION_SEP1997; newdstentry.z_lowgmt = newTimeStampLow; newdstentry.z_highgmt = newTimeStampHigh; newdstentry.
EDITREAD Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The EDITREAD procedure reads text lines from an EDIT file (file code=101). Text lines are transferred, in ascending order, from the text file to a buffer in the application program's data area. One line is transferred by each call to EDITREAD. EDITREAD also returns the sequence number associated with the text line and performs checks to ensure that the text file is valid.
bufferlen input INT:value is the length, in bytes, of the buffer array. This specifies the maximum number of characters in the text line that is transferred into buffer. sequence-num output INT(32):ref:1 returns the sequence number multiplied by 1000, in double-word integer form, of the text line just read. Returned Value INT A status value that indicates the outcome of the call: >= 0 Indicates that the reading of the file was successful. This is the actual number of characters in the text line.
EDITREADINIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The EDITREADINIT procedure is called to prepare a buffer in the application program's data area for subsequent calls to EDITREAD. The application program designates an array to be used as an edit control block. The edit control block is used by the EDITREAD procedure for storing control information and as an internal buffer area. The EDIT file can be opened nowait.
bufferlen input INT:value is the size, in bytes, of the internal buffer area used by EDITREAD. This parameter determines the amount of data that EDITREAD reads from the text file on disk (not the amount of data transferred into the buffer specified as a parameter to EDITREAD). The size of the internal buffer area must be a power of two, from 64 to 2048 bytes (that is, 64, 128, 256, ..., 2048). Returned Value INT A status value that indicates the outcome of the call: 0 Success (OK to read).
ERRNO_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Example Summary The ERRNO_GET_ procedure obtains the value of the errno variable set by many OSS, native C/C++, and some Guardian routines. Syntax for C Programmers C programmers using the C run-time libraries, CRE support libraries, or shared run-time libraries (SRLs) can access the errno variable directly and do not use this procedure. Syntax for TAL Programmers ?SOURCE $SYSTEM.SYSTEM.
EXTENDEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The EXTENDEDIT procedure copies an EDIT file to a new file that it creates and that has a larger extent size than the original file. It purges the old file and renames the new file to have the name of the old file. The lines in the new file are renumbered if so requested.
still occurs if increment is present, in which case the value of increment is used for start. The possible EDIT line numbers are 0, 0.001, 0.002, ... 99999.999. increment input INT(32):value if present and greater than 0, causes EXTENDEDIT to renumber the lines in the new file using the incremental value specified. The possible EDIT line numbers are 0, 0.001, 0.002, ... 99999.999. The value of increment indicates 1000 times the value to be added to each successive line number.
5 Guardian Procedure Calls (F) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter F. Table 14 lists all the procedures in this section.
Table 14 Procedures Beginning With the Letter F (continued) FILE_SETLASTERROR_ Procedure FILE_SETMODENOWAIT64_ Procedure FILE_SETPOSITION_ Procedure FILE_SETSYNCINFO_ Procedure FILE_UNLOCKFILE64_ Procedure FILE_UNLOCKREC64_ Procedure FILE_WRITE64_ Procedure FILE_WRITEREAD[64]_ Procedures FILE_WRITEUPDATE64_ Procedure FILE_WRITEUPDATEUNLOCK64_ Procedure FILEERROR Procedure FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure) FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure) FI
Table 14 Procedures Beginning With the Letter F (continued) FP_IEEE_DENORM_GET_ Procedure FP_IEEE_DENORM_SET_ Procedure FP_IEEE_ENABLES_GET_ Procedure FP_IEEE_ENABLES_SET_ Procedure FP_IEEE_ENV_CLEAR_ Procedure FP_IEEE_ENV_RESUME_ Procedure FP_IEEE_EXCEPTIONS_GET_ Procedure FP_IEEE_EXCEPTIONS_SET_ Procedure FP_IEEE_ROUND_GET_ Procedure FP_IEEE_ROUND_SET_ Procedure 345
FILE_ALTERLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Item Codes Considerations OSS Considerations Example Related Programming Manual Summary The FILE_ALTERLIST_ procedure changes certain attributes of a disk file that are normally set when the file is created.
number-of-items input INT:value is the number of items supplied in item-list. values input INT .EXT:ref:* is the array in which the values for the file attributes specified in item-list are supplied. The values should be supplied in the order specified in item-list. Each value begins on an INT boundary; if a value has a length that is an odd number of bytes, then an unused byte should occur before this value begins. The length of each fixed length value is given in Table 15.
Item Codes Table 15 lists the item codes for the file attributes that may be specified in item-list. NOTE: Items in this table with a size of 2 bytes are of data type INT. The term “disk file” applies only to Enscribe files. The term “disk object” applies to Enscribe files and SQL objects. Table 15 FILE_ALTERLIST_ Item Codes Code Size (Bytes) Description 42 2 File code. For disk objects other than SQL shorthand views, an application-defined value associated with the file.
Table 15 FILE_ALTERLIST_ Item Codes (continued) Code Size (Bytes) Description 93 * Partition-volume names. A string containing the concatenated names of all the secondary partition volumes, ordered by partition number. You can add new names or change old names; you cannot delete partition volume names. Each name occupies exactly the number of characters specified in the corresponding entry of item 92, hence the total length of this item is the sum of the values in item 92.
Table 15 FILE_ALTERLIST_ Item Codes (continued) Code Size (Bytes) Description Note that the alteration of key-sequenced files with these increased limits is not supported on legacy 514-byte sector disks, and the alteration attempt will fail with an FEINVALOP (2) error. For key-sequenced files in RVUs earlier than H06.28/J06.17, regardless of file organization or format: • If the alternate keys are unique, the maximum length is 253.
Table 15 FILE_ALTERLIST_ Item Codes (continued) Code Size (Bytes) Description 104 Alternate-file names. A string array containing the concatenated names of the alternate-key files. Since each name occupies exactly the number of characters specified in the corresponding entry of item 103, the total length of this item is the sum of the values in item 103. The names can be fully or partially qualified. Partially qualified names are resolved using the contents of the =_DEFAULTS DEFINE.
• If a partition or alternate-key file is not accessible, error 3 or 4 is returned. The accessible partitions or alternate-key files are still altered. • Exceeding the file system file label space An attempt to create a file receives an error 1027 if the file system file label space for the primary partition would be exceeded. If the file specification has up to 16 partitions, reduce the number of alternate-key files, alternate keys, extents, secondary partitions and/or the size of the partition keys.
FILE_AWAITIO64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Operation and Completion Summary Considerations OSS Considerations Related Programming Manual Summary The FILE_AWAITIO64_ procedure is used to complete a previously initiated I/O operation. Use FILE_AWAITIO64_ to: • • Wait for the operation to complete on: ◦ A particular file—Application process execution suspends until the completion occurs.
Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_AWAITIO64_) error := FILE_AWAITIO64_ ( filenum ,[ buffer-addr ] ,[ count-transferred ] ,[ tag ] ,[ timelimit ] ,[ segment-id ] ); ! ! ! ! ! ! i, o o o o i o Parameters filenum input, output INT .EXT64:ref:1 is the number of an open file. If a particular filenum is passed, FILE_AWAITIO64_ applies to that file. If filenum is passed as -1, the call to FILE_AWAITIO64_ applies to the oldest incomplete operation pending on each file.
timelimit input INT(32):value indicates whether the process waits for completion instead of checking for completion. If timelimit is passed in the following format: >0D A wait-for-completion is specified. The timelimit parameter specifies the maximum time (in .01-second units) from the time of the FILE_AWAITIO64_ procedure call that the application process can wait (that is, be on a wait list) for completion of a waited-for operation. See “Queue files” in Considerations (page 357).
Operation and Completion Summary The operation of the FILE_AWAITIO64_ procedure is shown in Figure 6 (page 356). Figure 6 FILE_AWAITIO64_ Operation NOTE: FILE_AWAITIO64_ returns the error code directly. How FILE_AWAITIO64_ completes depends on whether the filenum parameter specifies a particular file or any file and on what the value of timelimit is when passed with the call. The action taken by FILE_AWAITIO64_ for each combination of filenum and timelimit is summarized in Table 16.
Table 16 FILE_AWAITIO64_ Action Particular File (filenum = a file number) timelimit = 0 timelimit <> 0 CHECK for any I/O completion on filenum. WAIT for any I/O completion on filenum. COMPLETION COMPLETION File number is returned in filenum File number is returned in filenum. Tag of completed call is returned in tag. Tag of completed call is returned in tag. NO COMPLETION NO COMPLETION Error 40 is returned. Error 40 is returned. File number returned is in filenum.
is, the file number is other than -1). With non file-specific calls, FILE_READUPDATELOCK64_ is not canceled for the queue file. A canceled FILE_READUPDATELOCK64_ can result in the loss of a record from the queue file. For audited queue files, record loss can be avoided by performing an ABORTTRANSACTION procedure, when detecting error 40, to ensure that any dequeued record is reinserted into the file. For nonaudited queue files, there is no means of assuring recovery of a lost record.
• Normal order of I/O completion (without SETMODE function 30) If SETMODE function 30 is not set, the oldest incomplete I/O operation always completes first; therefore, FILE_AWAITIO64_ completes I/O operations associated with the particular open of a file in the same order as initiated. • Order of I/O completion with SETMODE function 30 Specifying SETMODE function 30 allows nowait I/O operations to complete in any order.
WARNING! On NSAA systems, the FILE_READ64_, FILE_WRITE64_ and FILE_WRITEREAD64_ procedures use the process file segment (PFS) of the caller to store the data being read or written. The maximum PFS size is 32 MB. This limits the number of concurrent no-wait operations with large read-count or write-count values. Perform the following steps to work around this limit: 1. Define the read and write buffers with sizes in multiples of 16KB. 2.
OSS Considerations When an OSS process calls FILE_AWAITIO64_ and an OSS signal occurs, the OSS function completes with error 4004 (EINTR). Even if FILE_AWAITIO64_ is used to wait for completion (timelimit <>0D) and a particular file is specified (filenum <> -1), this is not considered a completion and the oldest I/O operation against the file is not canceled. Call FILE_AWAITIO64_ again to complete the I/O operation.
FILE_CLOSE_Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Messages Related Programming Manuals Summary The FILE_CLOSE_ procedure closes an open file. Closing a file terminates access to the file. You can use FILE_CLOSE_ to close files that were opened by either FILE_OPEN_ or OPEN.
Returned Value INT A file-system error code that indicates the outcome of the call. No error is retryable; most of the possible error conditions are the result of programming errors. Considerations • Returning space allocation after closing a file Closing a disk file causes the space that is used by the resident file control block to be returned to the system main-memory pool if the disk file is not open concurrently. A temporary disk file is purged if the file was not open concurrently.
FILE_CLOSE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The FILE_CLOSE_CHKPT_ procedure is called by a primary process to close a designated file in its backup process. The backup process must be in the monitor state (that is, in a call to CHECKMONITOR) for FILE_CLOSE_CHKPT_ to be called successfully.
Returned Value INT A file-system error code that indicates the outcome of the call. Considerations • Identification of the backup process The system identifies the backup process to be affected by FILE_CLOSE_CHKPT_ from the process' mom field in the process control block (PCB). For named process pairs, this field is automatically set up during the creation of the backup process. • FILE_CLOSE_CHCKPT_ cannot be called for an SQL/MX object. • See the FILE_CLOSE_ procedure Considerations (page 363).
FILE_COMPLETE[L]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for completion-info Considerations Guardian Considerations OSS Considerations Related Programming Manuals Summary The FILE_COMPLETE[L]_ procedures complete one previously initiated I/O operation for a Guardian file or return ready information for one Open System Services (OSS) file.
• CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int.
Note that the FILE_COMPLETE[L]_ procedure does not perform as efficiently when this temporary override set is used. For better performance, you should use the "permanent" set of enabled files that is established by calling the FILE_COMPLETE_SET_ procedure. For information on how to set the field values of the COMPLETE^ELEMENT structure, see Structure Definitions for COMPLETE^ELEMENT (page 376).
Structure Definitions for completion-info The completion-info parameter is a structure that contains completion information for the Guardian file that was completed or the OSS file that is ready. The structures for the completion-info parameter are defined in the ZSYS* files. The TAL ZSYSTAL file defines two structures: one for the FILE_COMPLETE_ procedure, and one for the FILE_COMPLETEL_ procedure.
In the C ZSYSC file, the structure for the completion_info parameter is defined as: typedef struct __zsys_ddl_completion_info { short z_filetype; long z_error; long z_fnum_fd; union { struct { short filler_0:15; unsigned short filler_1:1; short filler_2:13; unsigned short z_read_ready:1; unsigned short z_write_ready:1; unsigned short z_exception:1; } z_return_value; unsigned long z_completion_type; long z_count_transferred; } u_z_return_value; long z_tag; } zsys_ddl_completion_info_def; Z^FILETYPE returns
Z^COUNT^TRANSFERRED returns the number of bytes transferred in the completed I/O operation on a Guardian file. (For OSS files, this field is replaced by Z^COMPLETION^TYPE.) Z^TAG for Guardian files, returns the application-defined tag that was specified when the completed I/O was initiated. This value is undefined if no tag was supplied for that I/O operation. For OSS files, this field contains 0. For the FILE_COMPLETEL_ procedure, this field is 64 bits.
example, the ready state of an OSS socket might be changed by another process that shares the socket before your process can initiate its I/O operation. The operation of checking for readiness is equivalent to calling the OSS select() function, except that the FILE_COMPLETE[L]_ procedure returns ready information for only one file at a time. For additional information, see the select(2) function reference page either online or in the Open System Services System Calls Reference Manual.
FILE_COMPLETE_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The FILE_COMPLETE_GETINFO_ procedure provides information about the set of files that are currently enabled for completion and thus can be completed by the FILE_COMPLETE_ procedure. These files were enabled for completion by one or more previous calls to the FILE_COMPLETE_SET_ procedure.
num-info-elements output INT .EXT returns the number of COMPLETE^ELEMENT structures that are returned in the info-list parameter. If this value is equal to the value specified for maxnum-info-elements, there might be additional files that are currently enabled for completion for which no information is being returned. Returned Value INT A file-system error code that indicates the outcome of the call.
FILE_COMPLETE_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for COMPLETE^ELEMENT Considerations Guardian Considerations OSS Considerations Summary The FILE_COMPLETE_SET_ procedure enables a set of Guardian and Open System Services (OSS) files for completion by subsequent calls to the FILE_COMPLETE_ procedure. (The FILE_COMPLETE_ procedure completes I/O operations for Guardian files and returns ready information for OSS files.
is the total number of Guardian files and OSS files specified in the complete-element-list parameter. error-complete-element output INT .EXT returns the index to a COMPLETE^ELEMENT structure in the complete-element-list parameter indicating the file that is in error. If an error occurs, the call has no affect on the previously established set of files enabled for completion.
Z^FNUM^FD is a Guardian file number or OSS file descriptor. Specifying a Guardian file number of -1D for completion indicates that completion of any Guardian file is requested; other specifically enabled Guardian file numbers are ignored. If you have specified a Guardian file number of -1D for completion, you cannot specify any single Guardian file for removal from the set of enabled files; you can only specify Guardian file number -1D.
Z^EXCEPTION can have these values: 0 Do not return exception ready for this file. 1 Return exception ready for this file. Considerations • Each file that is enabled for completion is enabled for multiple completions until your program removes it from the enabled set or closes it. Completion on a file does not remove it from the set of enabled files. • If the FILE_COMPLETE_SET_ procedure returns an error indication, the request (adding or removing the file from the enabled set) is not performed.
FILE_CONTROL64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manuals Summary The FILE_CONTROL64_ procedure is used to perform device-dependent I/O operations. FILE_CONTROL64_ extends the capabilities of the CONTROL procedure in the following ways: • It is callable from both 32-bit and 64-bit processes. • It allows a 64-bit nowait I/O tag to be passed.
operation input INT:value defines the operation to be performed. (See Table 10: CONTROL Operation 1 (page 207) and Table 11: CONTROL Operations 2 Through 27 (page 209) for the list of available operations.) param input INT:value is the value of the operation being performed (see Table 10: CONTROL Operation 1 (page 207) and Table 11: CONTROL Operations 2 Through 27 (page 209) ). tag input INT(64):value is for nowait I/O only.
NOTE: The CONTROL 2 operation is valid only for unstructured files or structured files opened for unstructured access. For XP-based files, using the CONTROL 2 operation to move the EOF will involve more CPU cycles. Writing the application data to the file and letting the disk process move the EOF as the data is written to the file, and removing the CONTROL 2 operations from the application code will improve the performance.
FILE_CONTROLBUF64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Messages Summary The FILE_CONTROLBUF64_ procedure is used to perform device-dependent I/O operations requiring a data buffer. FILE_CONTROLBUF64_ extends the capabilities of the CONTROLBUF procedure in the following ways: • It is callable from both 32-bit and 64-bit processes.
Parameters filenum input INT:value is the number of an open file. It identifies the file on which FILE_CONTROLBUF64_ performs an I/O operation. operation input INT:value defines the operation to be performed. (See Table 10: CONTROL Operation 1 (page 207) and Table 11: CONTROL Operations 2 Through 27 (page 209) for the list of available operations.
Considerations • EpTAL callers must set toggle EpTAL callers must set the toggle _64BIT_CALLS before sourcing the FILE_CONTROLBUF64_ section from EXTDECS. • Familiar semantics Unless otherwise described, the semantic behavior of FILE_CONTROLBUF64_ is same as that of CONTROLBUF. • Nowait and FILE_CONTROLBUF64_ If FILE_CONTROLBUF64_ is called on a file opened for nowait I/O, then the operation must be completed by calling either FILE_AWAITIO64_ or FILE_COMPLETEL_.
FILE_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_CREATE_ procedure is used to define a new structured or unstructured disk file. The file can be temporary (and therefore automatically deleted when closed) or permanent.
Syntax for TAL Programmers error := FILE_CREATE_ ( filename:maxlen ,filenamelen ,[ file-code ] ,[ primary-extent-size ] ,[ secondary-extent-size ] ,[ maximum-extents ] ,[ file-type ] ,[ options ] ,[ recordlen ] ,[ blocklen ] ,[ keylen ] ,[ key-offset ] ); ! ! ! ! ! ! ! ! ! ! ! ! i,o:i i,o i i i i i i i i i i Parameters filename:maxlen input, output:input STRING .
maximum-extents input INT:value specifies the maximum number of extents that can be allocated to the new file. The minimum and default value is 16. See Considerations (page 389) for the upper limit on this value. file-type input INT:value specifies the type of structure of the new file. If this parameter is omitted or equal to 0, an unstructured file is created. Valid values are: 0 Unstructured 1 Relative 2 Entry-sequenced 3 Key-sequenced options input INT:value specifies optional file attributes.
The formulas for computing the maximum record length (MRL) based on data-blocklen are: For this type of file MRL equals Relative and entry-sequenced files data-blocklen - 24 Key-sequenced files data-blocklen - 34 blocklen input INT:value for structured files, specifies the length in bytes of each block of records in the file. In H06.28/J06.
Considerations • File pointer action The end-of-file pointer is set to 0 after the file is created. • Disk allocation with FILE_CREATE_ Execution of the FILE_CREATE_ procedure does not allocate any disk area; it only provides an entry in the volume's directory, indicating that the file exists. • Altering file security The file is created with the caller's process file security, which can be examined and set with the PROCESS_SETINFO_ procedure.
• Disk accesses and the refresh EOF option If a disk file has the refresh EOF option set (options.<10> = 1), the file label is immediately written to disk each time the end-of-file (EOF) pointer is changed. (For a description of the refresh EOF option, see the information on unstructured disk files in the Enscribe Programmer's Guide.
OSS Considerations • This procedure operates only on Guardian objects. If an OSS file is specified, error 1163 is returned. • The OSS open() function always opens Guardian files with shared exclusion mode. Example file^type := 0; options.
FILE_CREATELIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Item Codes Considerations OSS Considerations Related Programming Manuals Summary The FILE_CREATELIST_ procedure is used to define a new structured or unstructured disk file. The file can be temporary (and therefore automatically deleted when closed) or permanent. When a temporary file is created, FILE_CREATELIST_ returns the file name in a form suitable for passing to the FILE_OPEN_ procedure.
Parameters filename:maxlen input, output:input STRING .EXT:ref:*, INT:value if a permanent file is to be created, is the name of the new file; if a temporary file is to be created, is the name of the disk volume on which the file is to be created. If the name is partially qualified, it is resolved using the contents of the caller's =_DEFAULTS DEFINE. If a temporary file is created, the name assigned to the file is returned in filename. maxlen is the length in bytes of the string variable filename.
Returned Value INT A file-system error code that indicates the outcome of the call. Item Codes Table 17 shows the item codes that can be specified when calling FILE_CREATELIST_. NOTE: Items in this table with a size of 2 bytes are of data type INT. The term "disk file" applies only to Enscribe files. The term "disk object" applies to Enscribe files and SQL objects. Table 17 FILE_CREATELIST_ Item Codes Item Size Code (Bytes) Description 41 File type.
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description 47 2 Lock-key length. For key-sequenced files, the generic lock-key length. The length must be between 1 and the key length of the file, or can be 0 to automatically use the key length of the file. The length must be 0 for non-key-sequenced files. 50 2 Primary extent size. For disk objects other than SQL shorthand views, an unsigned integer specifying the size of the first extent, in pages (2048-byte units).
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description volume; 0 indicates otherwise. When this item is not equal to 1, the system can choose to do either serial or parallel writes. The default value is 0. 80 2 Secondary partition. For disk objects, a value of 0 indicates a primary partition and a value of 1 indicates a secondary partition.
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description 98 * Partition-volume relative names-length array. An array of INT byte counts, each giving the length of volume-relative name (supplied in item 99) where the corresponding extra partition resides. The length of this item is two times item 90. 99 * Partition-volume relative names. Concatenated names of the extra partition volumes.
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description specifies a null value if attributes.<0> = 1. Note that the character must reside in the right-hand byte. null-value (INT:1) During a write operation, if a null value is specified for an alternate-key field, and if the null value is encountered in all bytes of this key field, the file system does not enter the reference to the record in the alternate-key file.
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description <0> Do not index when null. <1> Unique. <2> Do not update. <3> Insertion order duplicates. <4:15> Reserved. Must be zero. These fields have the same semantics as the corresponding fields of item 101. The length of this item in bytes is 14 times item 100. This item is an alternate form for item 101, and if used, must immediately follow item 100 in place of item 101.
Table 17 FILE_CREATELIST_ Item Codes (continued) Item Size Code (Bytes) Description 195 2 File format. File format can be 0, 1, or 2. Format 1 files allow only as many as 4 KB blocks and as many as 2 GB partitions. format 2 files allow larger blocks and partitions. The value 0 (the default) specifies that the system select the format based on the values of other parameters. 196 4 Logical record length (32-bit). For structured disk files, the maximum number of bytes in a logical record.
If item 65 is set to 1 and item 42 is set to 0 in item-list, an odd unstructured file is created. In that case, the values of record-specifier, read-count, and write-count are all interpreted exactly; for example, a write-count or read-count of 7 transfers exactly 7 bytes. • Even unstructured files If items 65 and 42 are both set to 0 in item-list, an even unstructured file is created.
record is not stored in the primary record.) The performance cost rises as the number of records having duplicate alternate-key values increases. If an insertion ordered alternate-key file is partitioned, the length of each partition key should be no greater than the total of the alternate-key tag length and the alternate-key length.
file with a key longer than 255 bytes with either index or data compression, an error 46 is returned. • ◦ The creation of files with these increased limits is not supported on legacy 514-byte sector disks, and the creation attempt will fail with an FEINVALOP (2) error. ◦ When using the C API to create a file with the 32,768 byte block length, you can avoid various C integer conversion warnings by using 0x8000 (32768 in hex).
FILE_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFO_ procedure obtains a limited set of information about a file identified by file number. A related procedure, FILE_GETINFOLIST_, obtains detailed information about a file identified by file number.
last-error output INT .EXT:ref:1 returns the file-system error number resulting from the last operation performed on the specified file. filename:maxlen output:input STRING .EXT:ref:*, INT:value returns the fully-qualified name under which the specified file was opened. If a DEFINE name was supplied when opening the file, filename is the file name, not the DEFINE name. maxlen gives the length in bytes of the string variable filename. filename-length output INT .
Returned Value INT A file-system error code that indicates the outcome of the call. Considerations • You can obtain the last-error value resulting from a file operation that is not associated with a file number by specifying a filenum value of -1 to FILE_GETINFO_. An error code can be obtained in this manner for such operations as a purge, waited open, or failed create operation. The result of a preceding awaitio[x] or alter operation can also be obtained in this manner.
FILE_GETINFOBYNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFOBYNAME_ procedure obtains a limited set of information about a file identified by file name. A related procedure, FILE_GETINFOLISTBYNAME_, obtains detailed information about a file identified by file name.
type-info output INT .EXT:ref:5 returns an array of INT values that contain information about the file. The meanings of the words are: [0] Device type [1] Device subtype [2:4] The meanings of these words depend on the device type. When the device type is 3 (disk) the meanings are: [2] Object type. For disk files, a value greater than 0 indicates an SQL object; 0 indicates a nonSQL file. -1 is returned for nondisk files. [3] File type.
options input INT:value specifies the options desired. The bits, when set to 1, indicate: <0:12> reserved (specify 0). <13> specifies that this call is only initiating a nowait inquiry and the information will be returned in a system message. Do not set both options.<13> and options.<14>. See Considerations (page 409). <14> specifies that the sending of a device type inquiry message to a subtype 30 process should not be allowed to take longer than indicated by tag-or-timeout.
incorrectly formatted, the FILE_GETINFOBYNAME_ caller receives device type and subtype values of 0. The REPLY caller (the subtype 30 process) receives an error 2. A deadlock occurs if a subtype 30 process calls FILE_GETINFOBYNAME_ on its own process name. • Using the nowait option If you call FILE_INFOBYNAME_ procedure in a nowait manner, the results are returned in the nowait FILE_GETINFOBYNAME_ completion message (-108), not in the output parameters of the procedure.
FILE_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Item Codes Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFOLIST_ procedure obtains detailed information about a file identified by file number. The information about a file is organized as a set of discrete items. The caller provides an input array parameter specifying a code for each item to be reported.
Parameters filenum input INT:value is a number that identifies the open file of interest. filenum was returned by FILE_OPEN_ or OPEN when the file was originally opened. You can also specify -1 for filenum to obtain the last-error value resulting from a file operation that is not associated with a file number. See Considerations (page 427). item-list input INT .EXT:ref.* is an array of values that specify the items of information to be returned by the procedure.
Returned Value INT A file-system error code that indicates the outcome of the call. Item Codes Table 18 shows the item codes used by FILE_GETINFOLIST_. Item codes of 30 and greater, except item codes 201 through 206, are also used by FILE_GETINFOLISTBYNAME_. NOTE: Items in this table with a size of 2 bytes are of data type INT. The term "disk file" applies only to Enscribe files. The term "disk object" applies to Enscribe files and SQL objects.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 15 * Current key value. For structured disk files, the current key value. Item 15 is not defined for queue files. This item cannot be used with the 64-bit primary-key election of the FILE_OPEN_ procedure; an attempt results in error 581. Superseded by item 204. 16 2 Current primary-key length. For structured disk files, the length in bytes of the current primary-key value. In H06.28/J06.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 33 2 Audited disk. For disk volumes and disk objects, 1 if the volume can support audited files; 0 otherwise. 34 2 Physical record length. For disk volumes and files, the maximum transfer length of the device; for processes and $RECEIVE, 132 by convention; for other devices, a configured value that generally represents some physical limit. This is always an unsigned value representing a number of bytes.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) 416 Item Code Size (Bytes) Description 50 2 Primary extent size. For disk objects other than SQL shorthand views, the size in pages (2048-byte units) of the first extent. A returned value of -1 means that the extent size cannot fit into this unsigned two-byte attribute. Item 199 must be used to get the correct value. Superseded by item 199. 51 2 Secondary extent size.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 69 2 Index compression. For key-sequenced disk objects, 1 if the entries in index blocks are to be compressed; 0 otherwise. 70 2 Refresh EOF. For disk objects other than SQL shorthand views, 1 if a change to the end-of-file value is to cause the file label to be written immediately to disk; 0 otherwise. 71 2 Create options.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description These values give the primary and secondary extent sizes in pages (2048-byte units). The length of this item in bytes is four times item 90. Superseded by item 97. 92 * Partition-volume name-length array. For disk files, an array of INT values, each giving the length in bytes of the volume name (supplied in item 93) on which the corresponding secondary partition resides.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 106 * Alternate-key descriptors (32-bit). An array of 14-byte descriptor entries, one for each alternate key. The structure of each entry is described under item 106 in Table 17 (page 394) (under FILE_CREATELIST_). The length in bytes of this item is 14 times the value of item 100. If this value has never been set, the key length of the file (the value of item 46) is returned. Supersedes item 101.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description means that the end-of-file value cannot fit into this unsigned four-byte attribute. Item 193 must be used to get the correct value. Superseded by item 193. 137 4 Partition maximum size.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 168 2 OSS number of links. Applies only to OSS files. 169 2 Security mechanisms in effect. For disk objects, the word of bits indicates the security mechanisms in effect for the given object. Note that the security mechanism of an object is not necessarily related to the overall security of the subvolume or volume. <0:10> reserved, reported as zero.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description maximum record length is 4048; for format 2 relative files, the maximum record length is 4044. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release (page 31).) For format 1 entry-sequenced and relative files, the maximum record length is 4072. If omitted, 80 is used. For queue files, this parameter must include 8 bytes for a timestamp.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description For earlier RVUs, the maximum alternate key length, regardless of whether it is a format 1 or format 2 file, varies based on the following factors: • If the alternate keys are unique, the maximum length is 253. • If the alternate key allows duplicates and is defined as insertion-ordered, the maximum length is 245 – primary key length.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 236 32 Disk drive types 2. For disk volume and disk objects, the types of drives on which the volume is mounted. This item returns the same information as the info item 114 (Disk Drive Type) except that it returns 16 bytes for each for the primary and secondary drives. Blanks are returned if one of the drives is not present. 237 10 ErrorSetExternally. For disk files, an array of 5 INT values is returned.
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 1005 2 1006 1007 1008 1009 2 2 2 2 Tape or Open SCSI process: Device subtype 1 unknown 0 passthrough mode 5 5120 tape drive 6 5160 or 5170 tape drive 7 5130 tape drive 8 5180 tape drive 9 5190 tape drive 10 5188 tape drive 11 5142 tape drive 14 521A, 524A, or 525A tape drives Tape process: Automatic Cartridge Loader (ACL) status -1 not installed or unknown 1 installed Tape process: Number
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 1 1013 1014 1015 1016 1017 1018 2 2 2 2 2 2 checksum mode Tape or Open SCSI process: Tracing level 0 no tracing x x tracing level Tape or Open SCSI process: Number of openers 1 1 opener (might be exclusive) x x openers Tape process: Current controller state -1 unknown 0 unloaded 1 loaded Tape process: Current assignment status -1 no applicable 0 unassigned 1 assigned (5188 tape drive only)
Table 18 FILE_GETINFOLIST_ Item Codes (continued) Item Code Size (Bytes) Description 3104 2 Tape process: Length in bytes of attribute 3105. 0 if no tape is mounted or the tape does not have labels. 3105 up to 160 Tape process: Current labels Beginning-of-file-section label group (HDR1, HDR2) of the current file. 1 Item code 235 is supported only on systems running H-series or J-series RVUs. Considerations • Normally if an error is returned, the contents of the result parameter are undefined.
the H06.28/J06.17 Release (page 31).) If the target file is a file with increased limits, then the file system may return up to 127 values, where previously only up to 63 values could be returned. Legacy applications that use a buffer for the result output parameter that is only big enough to contain the number of return values for earlier RVUs may get the FEBUFTOOSMALL (563) error when called on a file with the increased partition count limit.
FILE_GETINFOLISTBYNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFOLISTBYNAME_ procedure obtains detailed information about a file identified by file name. The information about a file is organized as a set of discrete items. The caller provides an input array parameter specifying a code for each item to be reported.
Parameters filename:length input:input STRING .EXT:ref:*, INT:value specifies the Guardian name of the file of interest. The value of filename must be exactly length bytes long and must be a valid file name or DEFINE name. If the name is partially qualified, it is resolved using the contents of the =_DEFAULTS DEFINE. item-list input INT .EXT:ref.* is an array of values that specify the items of information to be returned by the procedure.
Returned Value INT A file-system error code that indicates the outcome of the call. Considerations • Normally if an error is returned, the contents of the result parameter are undefined. However, if the returned error code is 2 (operation invalid for file type), the result parameter contains a combination of correct values (for valid items) and unchanged memory locations (for invalid items because of the kind of file). The error-item value points to the first invalid item.
• Secondary partition of non-SQL Enscribe files If the filename argument contains a secondary partition of an Enscribe file other than SQL, it returns only the value for the partition named. Only the primary partition of a file other than an SQL file has information on the other partitions in its label. Only when filename contains the primary partition do the aggregate items return the expected information. • Support for SQL files includes both format 1 and format 2 files.
OSS Considerations These item codes are not applicable to OSS objects but do not cause an error to be returned: 50, 51, 59, 60, 61, 62, 192, 199, and 200.
FILE_GETLOCKINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Summary The FILE_GETLOCKINFO_ procedure obtains information about locks (held or pending) on a local disk file or on a set of files on a local disk volume. Each call returns information about one lock and as many holders or waiters as permitted by the caller's request.
Parameters name:length input:input STRING .EXT:ref:*, INT:value specifies the name of the disk file or volume for which lock information is to be retrieved. The value of name must be exactly length bytes long and must be a valid disk file name or volume name; if processhandle or transid are specified, it must be a volume name. If the supplied name is partially qualified, it is resolved using the contents of the =_DEFAULTS DEFINE. The specified disk file or volume must be on the local system.
[5] The length in bytes of the key if the lock is a record lock on either a key-sequenced file or a format 2 non-key-sequenced file. In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the maximum length of the key if the lock is a record lock on a format 2 key-sequenced file is 2048 bytes. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release (page 31).) The length for earlier RVUs and for format 1 files, is 0.
[2:11] The processhandle of the participant (if participants[0].<0> = 1). [2:5] The transid of the participant (if participants[0].<0> = 0). max-participants input INT:value specifies the maximum number of lock holders and waiters that can be described in the participants buffer. locked-name:maxlen output:input STRING .
Considerations • The FILE_GETLOCKINFO_ procedure supports single SMF logical files but does not support entire SMF virtual volumes. If the name of an SMF logical file is supplied to this procedure, the system queries the disk process of the appropriate physical volume to obtain information about current lock holders and lock waiters on the file. If the name of an SMF virtual volume is supplied, but not a full logical file name, an error is returned.
FILE_GETOPENINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The FILE_GETOPENINFO_ procedure obtains information about the opens of one disk file or all the files on a disk device, or the opens of certain nondisk devices. Each call returns information about one open; make successive calls to FILE_GETOPENINFO_ to learn about all the opens.
Parameters searchname:length input:input STRING .EXT:ref:*, INT:value specifies the name of the disk file, volume, device, or subdevice about which open information is to be returned. The value of searchname cannot be a DEFINE name. If the name is partially qualified, it is resolved using the =_DEFAULTS DEFINE. prevtag input, output FIXED .EXT:ref:1 is a value identifying the open that was last returned. Before the first call, initialize prevtag to 0; on subsequent calls, pass the parameter unchanged.
filename:maxlen output:input STRING .EXT:ref:*, INT:value returns the fully qualified file name of the file about which information is being returned. maxlen is the length in bytes of the string variable filename. filenamelen output INT .EXT:ref:1 is the length in bytes of the name returned in filename. accessid output INT .EXT:ref:1 is the process access ID (user ID) of the opener at the time the open was done. validmask output INT .
Example ! The following code causes the names of all open files and ! the process handles of the primary and backup openers to be ! returned for the volume identified by search^name:length.
FILE_GETRECEIVEINFO[L]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The FILE_GETRECEIVEINFO[L]_ procedures return information about the last message read on the $RECEIVE file. Because this information is contained in the file's main-memory resident access control block (ACB), the application process is not suspended by a call to FILE_GETRECEIVEINFO[L]_.
Parameters receive-info output INT .EXT:ref:17 (for FILE_GETRECEIVEINFO_) is a block of words describing the last message read on the $RECEIVE file. It has this structure: [0] I/O type. Indicates the data operation last performed by the message sender. Values are: 0 Not a data message (system message). 1 Sender called WRITE. 2 Sender called READ. 3 Sender called WRITEREAD. [1] Maximum reply count.
using for dialogs. The server can abort the dialog, by replying with FEEOF, to enforce a level of transaction control that the requester has not specified. [15] Reserved. receive-info2 output INT .EXT:ref:* (for FILE_GETRECEIVEINFOL_) is a block of 19 words describing the last message read on the $RECEIVE file. It has this structure: [0] I/O type. Indicates the data operation last performed by the message sender. Values are: 0 Not a data message (system message). 1 Sender called WRITE.
Considerations • Sync ID definition A sync ID is a doubleword, unsigned integer. Each opened process has its own sync ID. Sync IDs are not part of the message data; rather, the receiver of a message obtains the sync ID value associated with a particular message by calling FILE_GETRECEIVEINFO[L]_. A file's sync ID is set to 0 when the file is opened and when the RESETSYNC procedure is called for that file (RESETSYNC can be called directly or indirectly through the CHECKMONITOR procedure).
FILE_GETSYNCINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The FILE_GETSYNCINFO_ procedure is called by the primary process of a process pair before starting a series of write operations to a file open with paired access. FILE_GETSYNCINFO_ returns a file's synchronization block so that it can be sent to the backup process in a checkpoint message.
infosize output INT .EXT:ref:1 returns the size in bytes of the information stored in the infobuf parameter. Returned Value INT A file-system error code that indicates the outcome of the call. Considerations • • In H06.28/J06.
non-key-sequenced files, and the maximum alternate-key length is the maximum value of all the alternate keys for the file. ◦ For any supported file type, an infomax value of 300 is sufficient.
FILE_LOCKFILE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Related Programming Manual Summary The FILE_LOCKFILE64_ procedure is used to exclude other users from accessing a file (and any records within that file). The "user" is defined either as the opener of the file (identified by the filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
Parameters filenum input INT:value is the number of an open file that identifies the file to be locked. tag input INT(64):value for nowait I/O only, is a value you define that uniquely identifies the operation associated with this FILE_LOCKFILE64_ procedure call. NOTE: The system stores the tag value until the I/O operation completes.
• Locks and open files—applies to non-audited files only Locks are granted on an open file (that is, file number) basis. Therefore, if a process has multiple opens of the same file, a lock of one file number excludes access to the file through other file numbers.
FILE_LOCKREC64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Related Programming Manual Summary The FILE_LOCKREC64_ procedure excludes other users from accessing a record at the current position. The "user" is defined either as the opener of the file (identified by the filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_LOCKREC64_) error := FILE_LOCKREC64_ ( filenum ,[ tag ] ); ! i ! i Parameters filenum input INT:value is the number of an open file that identifies the file to be locked. tag input INT(64):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with FILE_LOCKREC64_ . NOTE: The system stores the tag value until the I/O operation completes.
• Alternate locking mode If the record is already locked by another user when FILE_LOCKREC64_ is called, the lock request is rejected, and the call to FILE_LOCKREC64_ completes immediately with file-system error 73 (record is locked). The alternate locking mode is specified by calling the FILE_SETMODENOWAIT64_ procedure and specifying function 4.
to RBA-2. Depending on the process' locking mode, the call either fails with file-system error 73 ("record is locked") or is placed in the locking queue. ◦ Record pointers after FILE_LOCKREC64_ After a call to FILE_LOCKREC64_, the current-record, next-record, and end-of-file pointers remain unchanged. • Avoiding or resolving deadlocks One way to avoid deadlock is to use one of the alternate locking modes that can be established by function 4 of the FILE_SETMODENOWAIT64_ procedure.
FILE_OPEN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value General Considerations Disk File Considerations Terminal Considerations Interprocess Communication Considerations DEFINE Considerations Safeguard Considerations Restricted-Access Fileset Considerations OSS Considerations Messages Example Related Programming Manuals Summary The FILE_OPEN_ procedure establishes a communication path between an application process and a file.
Syntax for TAL Programmers error := FILE_OPEN_ ( { filename | pathname }:length } ,filenum ,[ access ] ,[ exclusion ] ,[ nowait-depth ] ,[ sync-or-receive-depth ] ,[ options ] ,[ seq-block-buffer-id ] ,[ seq-block-buffer-len ] ,[ primary-processhandle ] ,[ elections ] ); ! ! ! ! ! ! ! ! ! ! ! i:i i,o i i i i i i i i i Parameters filename:length input:input STRING .EXT:ref:*, INT:value specifies the name of the Guardian file to be opened.
exclusion input INT:value specifies the desired mode of compatibility with other openers of the file. (See General Considerations (page 461).) Valid values are: 0 Shared 1 Exclusive 2 Process exclusive 3 Protected The default is 0. nowait-depth input INT:value specifies whether I/O operations are to be nowait. If present and not 0, this parameter specifies the number of nowait I/O operations that can be in progress for the file concurrently with other processing.
number of operations to be saved; in case of path failures, the operations are retried automatically. The actual value being used can be obtained by a call to FILE_GETINFOLIST_. options input INT:value specifies optional characteristics. The bits, when set to 1, indicate: <0> Unstructured access. For disk files, access is to occur as if the file were unstructured, that is, without regard to record structures and partitioning.
seq-block-buffer-len input INT:value specifies whether sequential block buffering is being requested. If this parameter is supplied with a value greater than 0, it indicates a request for sequential block buffering and specifies the length in bytes of the sequential block buffer. If this parameter is omitted or 0, sequential block buffering is not requested. Sequential block buffering is only for disk files.
assigned, except in the case of backup opens. When a file is closed, its file number becomes available for a subsequent file open to use. • Maximum number of open files The maximum number of files in the system that can be open at any given time depends on the space available for control blocks: access control blocks (ACBs), file control blocks (FCBs), and open control blocks (OCBs). The amount of space available for control blocks is limited primarily by the physical memory size of the system.
• $0.#ZSPI 128 concurrent opens permitted. $OSP 10 times the number of subdevices (up to a maximum of 830 opens). $RECEIVE One open per process permitted. Other Varies by subsystem. Nowait I/O Specifying a nowait-depth value greater than 0 causes all I/O operations to be performed in a nowait manner. Nowait I/O operations must be completed by a call to AWAITIO[X].
• Named processes If you supply a process file name for a named process, it can represent any process with the same name. System messages are normally sent to the current primary process. The exception is when a named process supplies its own name to FILE_OPEN_. In that case the name refers to the backup process and system messages are sent there. A named process can be represented with or without a sequence number. FILE_OPEN_ treats the two name forms differently.
For a given access mode, the accessor's security level is checked against the file security level. File access is allowed or not allowed as shown in Table 20. In this table, file security levels are indicated by FUP security codes. For a given accessor security level, a Y indicates that access is allowed to a file with the security level shown; a hyphen indicates that access is not allowed.
Figure 7 Exclusion and Access Mode Checking • Applications with large receive-depth values If you have applications that use large receive-depth values, you must periodically monitor their Message Quick Cell (MQC) usage levels using the PEEK /CPU N/ MQCINFO command processors to make sure that the total amount of memory allocated for MQCs does not approach the per-processor memory limit for MQCs. This limit is 128 MB in H06.19/J06.08 and earlier RVUs, and 1 GB in H06.20/J06.09 and later RVUs.
next-record pointer=0D ◦ Sharing the same EOF pointer If a given disk file is opened more than once by the same process, separate current-record and next-record pointers are provided for each open, but all opens share the same EOF pointer. • Structured files ◦ Accessing structured files as unstructured files The unstructured access option (options.<0> = 1) permits a file to be accessed as an unstructured file.
SETSYNCINFO) and the 32-bit key items of the FILE_GETINFOLIST_, FILEINFO, and FILERECINFO procedures. • Format 2 key-sequenced files with increased limits not supported on legacy 514-byte sector disks FILE_OPEN_ does not support the open of format 2 key-sequenced files with increased limits (in H06.28/J06.17 RVUs with specific SPRs and later RVUs) on legacy 514-byte sector disks. The open attempt will fail with an FEINVALOP (2) error.
process name consisting of more than five characters will fail with an error 20. Notification of this failure is not sent to the process reading $RECEIVE. • Opening an unconverted (C-series format) process from a high-PIN process. A high-PIN process cannot open an unconverted process unless the unconverted process has the HIGHREQUESTERS object-file attribute set.
Messages When a process is opened by either FILE_OPEN_ or OPEN, it receives a process open message (unless it specified when opening $RECEIVE that it wants no messages). This message is in D-series format (message -103) or in C-series format (message -30), depending on what the receiving process specified when it opened $RECEIVE. The process handle of the opener can be obtained by a subsequent call to FILE_GETRECEIVEINFO_.
FILE_OPEN_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The FILE_OPEN_CHKPT_ procedure is called by a primary process to open a designated file for its backup process. These two conditions must be met before FILE_OPEN_CHKPT_ can be called successfully: • The primary process must open the file. • The backup process must be in the "monitor" state (that is, in a call to CHECKMONITOR).
Returned Value INT A file-system error number indicating the outcome of the checkpoint operation. Additional error information is returned in the status parameter. Considerations • Identification of the backup process The system identifies the backup process to be affected by FILE_OPEN_CHKPT_ from the process' mom field in the process control block (PCB). For named process pairs, this field is automatically set up during the creation of the backup process.
FILE_PURGE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_PURGE_ procedure deletes a disk file that is not open. When FILE_PURGE_ is executed, the disk file name is deleted from the volume's directory, and any disk space previously allocated to that file is made available to other files.
Considerations • Purging a file audited by the Transaction Management Facility (TMF) subsystem If the file is audited by the TMF subsystem and if there are pending transaction-mode record locks or file locks, any attempt to purge the file fails with file-system error 12, whether or not openers of the file still exist. When an audited file is purged, all corresponding dump records are deleted from the TMF catalog.
FILE_READ64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Disk File Considerations Related Programming Manuals Summary The FILE_READ64_ procedure returns data from an open file to the application process' data area. FILE_READ64_ is intended for use with 64-bit extended addresses. The data buffer for FILE_READ64_ can be either in the caller's stack segment or any extended data segment. FILE_READ64_ sequentially reads a disk file.
Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_READ64_) error := FILE_READ64_ ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters filenum input INT:value is the number of an open file that identifies the file to be read. buffer output STRING .EXT64:ref:* is an array where the information read from the file is returned. The buffer can be in the caller's stack segment or in any extended data segment.
Returned Value INT A file-system error code that indicates the outcome of the call. 1 FILE_READ64_ procedure was passed a filenum for an unstructured open of the primary partition of an enhanced key-sequenced file. For more information on enhanced key-sequenced files, see the Enscribe Programmer's Guide 22 • The address of a parameter refers to the selectable segment area but no selectable segment is in use at the time of the call.
NOTE: A deadlock condition occurs if a call to FILE_READ64_ is made by a process having multiple opens on the same file and the filenum used to lock the file differs from the filenum supplied to FILE_READ64_. • Read call when alternate locking mode is in effect If the alternate locking mode is in effect when FILE_READ64_ is called, and the file or record is locked through a file number other than that supplied in the call, the call is rejected with file-system error 73 (file is locked).
(PFS) for I/O transfers. A file opened by OPEN uses a PFS buffer for I/O transfers, except for large transfers to DP2 disks. ◦ • If the extended address of the buffer is odd, bounds checking rounds the address to the next lower word boundary and checks an extra byte as well. The odd address is used for the transfer. Queue files FILE_READ64_ can be used to perform a nondestructive read of a queue file record.
than the current key. Subsequent reading of the subset returns successive records until the last record in the file is read (an EOF indication is then returned). ◦ Reading of a generic subset of records If a generic subset is being read, the first record returned is the one whose key field, as designated by the current key-specifier, contains a value equal to the current key for compare-length bytes.
You set the odd unstructured attribute with the FILE_CREATE_, FILE_CREATELIST_, or CREATE procedure, or with the File Utility Program (FUP) SET and CREATE commands. ◦ FILE_READ64_ count Unstructured files are transparently blocked. The BUFFERSIZE file attribute value, if not set by the user, defaults to 4096 bytes. The BUFFERSIZE attribute value (which is set by specifying SETMODE function 93) does not constrain the allowable read-count in any way.
FILE_READLOCK64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Related Programming Manuals Summary The FILE_READLOCK64_ procedure sequentially locks and reads records in a disk file, exactly like the combination of FILE_LOCKREC64_ and FILE_READ64_. FILE_READLOCK64_ is intended for use with 64-bit extended addresses.
Parameters filenum input INT:value is the number of an open file that identifies the file to be read. buffer output STRING .EXT64:ref:* is an array in the application process where the information read from the file returns. read-count input INT(32):value is the number of bytes to be read: {0:4096}. count-read output INT(32) .EXT64:ref:1 for wait I/O only, returns a count of the number of bytes returned from the file into buffer.
• Nowait I/O and FILE_READLOCK64_ If the FILE_READLOCK64_ procedure is used to initiate an operation with a file opened nowait, it must complete with a corresponding call to either FILE_AWAITIO64_ or FILE_COMPLETEL_. WARNING! When using nowait file I/O, data corruption might occur if the read buffer is modified before either FILE_AWAITIO64_ or FILE_COMPLETEL_ completes the call. The buffer space must not be freed or reused while the I/O is in progress.
• ◦ A file opened by FILE_OPEN_ uses direct I/O transfers by default; you can use SETMODE function 72 to force the system to use an intermediate buffer in the process file segment (PFS) for I/O transfers. A file opened by OPEN uses a PFS buffer for I/O transfers, except for large transfers to DP2 disks. ◦ If the extended address of the buffer is odd, bounds checking rounds the address to the next lower word boundary and checks an extra byte as well. The odd address is used for the transfer.
FILE_READUPDATE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Disk File Considerations Interprocess Communication Considerations Related Programming Manuals Summary The FILE_READUPDATE64_ procedure reads data from a disk or process file in anticipation of a subsequent write to the file. FILE_READUPDATEL64_ is intended for use with 64-bit extended addresses.
Syntax for C Programmers #include short FILE_READUPDATE64_ ( short filenum ,char _ptr64 *buffer ,__int32_t read-count ,[ __int32_t _ptr64 *count-read ] ,[ long long tag ] ); Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_READUPDATE64_) error := FILE_READUPDATE64_ ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters filenum input INT:value is the number of an open file that identifies the file to be read.
NOTE: The system stores the tag value until the I/O operation completes. It then returns the tag information to the program in either the tag parameter of the call to FILE_AWAITIO64_ or the tag field of the completion-info parameter of the call to FILE_COMPLETEL_, thus indicating that the operation finished. Returned Value INT A file-system error code that indicates the outcome of the call. 0 FEOK Successful operation. 6 FESYSMESSAGE Successful operation that reads a system message.
If a nowait FILE_READUPDATE64 is executed, then the operation must be completed by calling either FILE_AWAITIO64_ or FILE_COMPLETEL_. WARNING! When using nowait file I/O, data corruption might occur if the read buffer is modified before either FILE_AWAITIO64_ or FILE_COMPLETEL_ completes the call. The buffer space must not be freed or reused while the I/O is in progress.
◦ Nowait I/O initiated with this routine can be canceled with a call to CANCEL or CANCELREQL. The I/O is canceled if the file is closed before the I/O finishes or FILE_AWAITIO64_ is called with a positive time limit and specific file number, and the request times out. ◦ A file opened by FILE_OPEN_ uses direct I/O transfers by default; you can use SETMODE function 72 to force the system to use an intermediate buffer in the process file segment (PFS) for I/O transfers.
count-read := $MIN(read-count,EOF - next-record - next-record pointer) ◦ Number of bytes read If the unstructured file is created with the odd unstructured attribute (also known as ODDUNSTR) set, the number of bytes read is exactly the number specified with read-count. If the odd unstructured attribute is not set when the file is created, the value of read-count is rounded up to an even value before the FILE_READUPDATE64_ is executed.
FILE_READUPDATELOCK64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Related Programming Manuals Summary The FILE_READUPDATELOCK64_ procedure is used for random processing of records in a disk file. FILE_READUPDATELOCK64_ is intended for use with 64-bit extended addresses. The data buffer for FILE_READUPDATELOCK64_ can be either in the caller's stack segment or any extended data segment.
Syntax for C Programmers #include short FILE_READUPDATELOCK64_ ( short filenum ,char _ptr64 *buffer ,unsigned int read-count ,[ unsigned int _ptr64 *count-read ] ,[ long long tag ] ); Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_READUPDATELOCK64_) error := FILE_READUPDATELOCK64_ ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters filenum input INT:value is the number of an open file that identifies the file t
Returned Value INT A file-system error code that indicates the outcome of the call. • The address of a parameter is extended, but either the extended data segment is invalid or the address is for a selectable segment that is not in use at the time of the call. 22 • The address of a parameter is extended, but it is an absolute address and the caller is not privileged.
finishes with a call to FILE_AWAITIO64_ or FILE_COMPLETEL_ or is canceled by a call to CANCEL or CANCELREQL. ◦ If the file is opened for nowait I/O, you must not modify the buffer before the I/O finishes with a call to FILE_AWAITIO64_ or FILE_COMPLETEL_. This also applies to other processes that might be sharing the segment. It is the application's responsibility to ensure this.
FILE_RENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_RENAME_ procedure changes the name of an open disk file. If the file is temporary, assigning a name causes the file to be made permanent. FILE_RENAME_ returns an error if there are incomplete nowait operations pending on the specified file.
Returned Value INT A file-system error code that indicates the outcome of the call. Considerations • Purge access for FILE_RENAME_ The caller must have purge access to the file for the rename operation to be successful; otherwise, FILE_RENAME_ returns error 48 (security violation). • Volume specification for newname The disk volume designated in newname (explicitly or implicitly) must be the same as the volume specified when opening the file.
Example error := FILE_RENAME_ ( filenum, name:name^length ); Related Programming Manuals For programming information about the FILE_RENAME_ procedure, see the Guardian Programmer's Guide.
FILE_REPLY64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The FILE_REPLY64_ procedure is used to send a reply message to a message received earlier in a corresponding call to READUPDATE[X|XL] or FILE_READUPDATE64_ on the $RECEIVE file. FILE_REPLY64_ is intended for use with 64-bit extended addresses. FILE_REPLY64_ can be called even if there are incomplete nowait I/O operations pending on $RECEIVE.
write-count input INT(32):value is the number of bytes to be written ({0:2097152}). If omitted or 0, no data is returned. count-written output INT(32) .EXT64:ref:* returns a count of the number of bytes written to the file. message-tag input INT:value is the message-tag returned from FILE_GETRECEIVEINFOL_ (or FILE_GETRECEIVEINFO_ or LASTRECEIVE or RECEIVEINFO) that associates this reply with a message previously received.
• Replying to queued messages Several interprocess messages can be read and queued by the application process before a reply must be made. The maximum number of messages that the application process expects to read before a corresponding reply must be specified in the receive-depth parameter to the FILE_OPEN_ or OPEN procedure. If $RECEIVE is opened with receive-depth = 0, only FILE_READ64_ can be called; FILE_READUPDATE64_ and FILE_REPLY64_ fail with error 2 ("operation not allowed on this type of file").
FILE_RESTOREPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The FILE_RESTOREPOSITION_ procedure supersedes the REPOSITION Procedure (Superseded by FILE_RESTOREPOSITION_ Procedure) (page 1246) and is used to position a disk file to a saved position (the positioning information having been saved by a call to the FILE_SAVEPOSITION_ Procedure (page 504)).
savesize input INT:value is the size in bytes of the information in the savearea parameter. In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the maximum value that can be specified for this parameter is larger than previously allowed. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release (page 31).) Applications never explicitly set this value; it is the value returned by the FILE_SAVEPOSITION_ procedure.
FILE_SAVEPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The FILE_SAVEPOSITION_ procedure supersedes the SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure) (page 1257) , and is used to save a disk file's current file positioning information in anticipation of a need to return to that position.
savesize output INT .EXT:ref:1 returns the size in bytes of the information in the savearea parameter. Returned Value INT A file-system error code that indicates the status of the operation. Considerations • • In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the size of the savemax parameter has been increased for format 2 key-sequenced files that use increased key size limits. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.
FILE_SETKEY_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The FILE_SETKEY_ procedure supersedes the KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) (page 750). The FILE_SETKEY_ procedure is used to position by primary or alternate key within a structured file.
key-value:key-value-len input, input STRING.EXT:ref:*, INT:value is the key value (with its length in bytes) to which the file is to be positioned. In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the maximum value of key-value-len for key-sequenced files with increased limits is 2048. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release (page 31).
is the length (in bytes) of the key used for comparing generic mode and exact-positioning mode that is used to decide when to stop returning these records. The value must be no longer than the key-value-len value. If omitted or 0, the value used is the smaller value of key-value-len or keylength of the key specified by the keyspecifier parameter. Returned Value INT A file-system error code that indicates the status of the operation.
FILE_SETLASTERROR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The FILE_SETLASTERROR_ procedure is used to set the error information for a file identified by the file number. This procedure can be used to set the Enscribe file-system error values: last-error, last-error detail, partition, and key in error.
errkey input INT:value specifies the key associated with the error for files with alternate keys. errdetail input INT:value sets the value of the last-error detail. Last-error detail indicates additional information, if available, for interpreting the errorcode. This value might be a file-system error number or another kind of value, depending on the operation and the primary error. Returned Value INT A file-system error code that indicates the outcome of the call.
FILE_SETMODENOWAIT64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manuals Summary The FILE_SETMODENOWAIT64_ procedure is used to set device-dependent functions. FILE_SETMODENOWAIT64_ extends the capabilities of SETMODENOWAIT in the following ways: • It is callable from both 32-bit and 64-bit processes. • It allows a 64-bit nowait I/O tag to be passed.
Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_SETMODENOWAIT64_) error := FILE_SETMODENOWAIT64_ ( filenum ! ,function ! ,[ param1 ] ! ,[ param2 ] ! ,[ last-params ] ! ,[ tag ] ); ! i i i i o i Parameters filenum input INT:value is a number of an open file, identifying the file to receive the FILE_SETMODENOWAIT64_ function. function input INT:value is one of the device-dependent functions listed in Table 44 (page 1319).
NOTE: The system stores the tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to FILE_AWAITIO64_ or the tag field of the completion-info parameter of the call to FILE_COMPLETEL_, thus indicating that the operation finished. If the tag argument is omitted, the value 0F is used. Returned Value INT A file-system error code that indicates the outcome of the call.
FILE_SETPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The FILE_SETPOSITION_ procedure supersedes the POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) (page 975). This procedure has the same function as the POSITION procedure but the FILE_SETPOSITION_ procedure accepts an eight-byte record specifier.
A value of -2 specifies that the next write should occur at an unused record position. Relative Files The recordspecifier parameter is an eight-byte recordnum value. A value of -2 specifies that the next write must occur at an unused record position. A value of -1 specifies that subsequent writes must be appended to the end-of-file location.
FILE_SETSYNCINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The FILE_SETSYNCINFO_ procedure supersedes the SETSYNCINFO Procedure (Superseded by FILE_SETSYNCINFO_ Procedure) (page 1355). Unlike the SETSYNCINFO procedure, this procedure can be used with Enscribe format 2 files and OSS files greater than approximately 2 gigabytes as well as with other files.
infobuf input INT .EXT:ref:* is the synchronization information returned by the FILE_GETSYNCINFO_ procedure. infosize input INT:value is the size in bytes of the infobuf parameter. In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the maximum value that can be specified for this parameter is larger than previously allowed. (For a list of the required H06.28/J06.17 SPRs, see SPR Requirements for Increased Enscribe Limits for the H06.28/J06.17 Release (page 31).
FILE_UNLOCKFILE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manual Summary The FILE_UNLOCKFILE64_ procedure unlocks a disk file and any records in the file currently locked by the user. The "user" is defined either as the opener of the file (identified by the filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
tag input INT(64):value for nowait I/O only, is a value you define that uniquely identifies the operation associated with this FILE_UNLOCKFILE64_. NOTE: The system stores the tag value until the I/O operation completes. It then returns the tag information to the program in either the tag parameter of the call to FILE_AWAITIO64_ or the tag field of the completion-info parameter of the call to FILE_COMPLETEL_, thus indicating that the operation finished.
Related Programming Manual For programming information about the FILE_UNLOCKFILE64_ procedure, see the Enscribe Programmer's Guide and the Guardian Programmer's Guide.
FILE_UNLOCKREC64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manual Summary The FILE_UNLOCKREC64_ procedure unlocks a record currently locked by the user. The "user" is defined either as the opener of the file (identified by the filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
tag input INT(64):value for nowait I/O only, is a value you define that uniquely identifies the operation associated with this FILE_UNLOCKREC64_. NOTE: The system stores the tag value until the I/O operation completes. It then returns the tag information to the program in either the tag parameter of the call to FILE_AWAITIO64_ or the tag field of the completion-info parameter of the call to FILE_COMPLETEL_, thus indicating that the operation finished.
• File pointers after FILE_UNLOCKREC64_ For unstructured files, the current-record pointer and the next-record pointer remain unchanged. • Transaction Management Facility (TMF) and FILE_UNLOCKREC64_ A record that is locked in a file audited by TMF and has been modified by the current transaction is unlocked when an ABORTTRANSACTION or ENDTRANSACTION procedure is called for that file. Locks on modified records of audited files are released only when the transaction is ended or aborted by TMF.
FILE_WRITE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Disk File Considerations Interprocess Communication Considerations Related Programming Manuals Summary The FILE_WRITE64_ procedure writes data from an array in the application program to an open file. FILE_WRITE64_ is intended for use with 64-bit addresses. The data buffer for FILE_WRITE64_ can be either in the caller's stack segment or any extended data segment.
Parameters filenum input INT:value is a number of an open file that identifies the file to be written. buffer input STRING .EXT64:ref:* is an array containing the information to be written to the file.
Returned Value INT A file-system error code that indicates the outcome of the call. 22 FEBOUNDSERR • The address of a parameter refers to the selectable segment area but no selectable segment is in use at the time of the call. • The address of a parameter is extended, but it is an absolute address and the caller is not privileged. • The file system cannot use the user's segment when needed.
I/O operation because this creates the possibility of changing the contents of the write buffer before the write is completed • Buffer considerations ◦ The buffer and count transferred can be in the user stack or in an extended data segment. The buffer and count transferred cannot be in the user code space. ◦ If the buffer or count transferred is in a selectable extended data segment, the segment must be in use at the time of the call.
size) is 4 KB (4096). Default mode here refers to the mode of the file if SETMODE function 141 is not invoked. For an unstructured file with an unstructured buffer size other than 4 KB, DP2 automatically adjusts the unstructured buffer size to 4 KB, if possible, when an I/O larger than 4KB is attempted. However, this adjustment is not possible for files that have extents with an odd number of pages; in such cases an I/O over 4 KB is not possible.
• Structured files ◦ Inserting records into relative and entry-sequenced files If the insertion is to a relative or entry-sequenced file, the file must be positioned currently through its primary key. Otherwise, FILE_WRITE64_ fails with an error 46 (invalid key). ◦ Current-state indicators after FILE_WRITE64_ After a successful FILE_WRITE64_, the current-state indicators for positioning mode and comparison length remain unchanged.
Interprocess Communication Considerations • Indication that the destination process is running If the FILE_WRITE64_ call is to another process, successful completion of FILE_WRITE64_ (or FILE_AWAITIO64_, if nowait) indicates that the destination process is running. Related Programming Manuals For programming information about the FILE_WRITE64_ procedure, see the Guardian Programmer's Guide, the Enscribe Programmer's Guide, and the data communication manuals.
FILE_WRITEREAD[64]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The FILE_WRITEREAD[64]_ procedures perform a writeread request to a file. For no-wait files, the user program is returned to after the request is initiated. For waited files, the completion is waited for, and then the data is moved into the user buffer. The count read will not be returned back for no-waited calls.
Syntax for C Programmers #include short FILE_WRITEREAD_ ( short filenum ,char _far *write-buffer ,char _far *read-buffer ,__int32_t write-count ,__int32_t read-count ,[ __int32_t _far *count-read ] ,[ __int32_t tag ] ); #include short FILE_WRITEREAD64_( short filenum ,const char _ptr64 *write-buffer ,[ char _ptr64 *read-buffer ] ,__int32_t write-count ,__int32_t read-count ,[ __int32_t _ptr64 *count-read ] ,[ long long tag ] ); Syntax for TAL Progr
read-buffer output STRING .EXT:ref:* (for FILE_WRITEREAD_) STRING .EXT64:ref:* (for FILE_WRITEREAD64_) is an array that contains the information that was read from the file on return. write-count input INT(32):value is the number of bytes to be written: {0:32755} for terminals (for FILE_WRITEREAD64_ only) , or {0:57344} for interprocess files.
Returned Value INT A file-system error code that indicates the outcome of the call. • The address of a parameter refers to the selectable segment area but no selectable segment is in use at the time of the call. 22 • The address of a parameter references a privileged segment and the caller is not privileged. • The file system cannot use the user's segment when needed.
I/O operation completes with a call to the FILE_AWAITIO64_ or FILE_COMPLETEL_ procedure or the call is canceled by a call to CANCEL or CANCELREQL. ◦ If the file is opened for nowait I/O, the extended segment containing the buffers must be in use at the time of the call to the AWAITIOX , FILE_AWAITIO64_, or FILE_COMPLETE[L]_ procedure. ◦ Nowait I/O initiated with these routines might be canceled with a call to CANCEL or CANCELREQ[L].
FILE_WRITEUPDATE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Disk File Considerations Magnetic Tape Considerations Example Related Programming Manuals Summary The FILE_WRITEUPDATE64_ procedure transfers data from an array in the application program to a file. The data buffer for FILE_WRITEUPDATE64_ can be either in the caller's stack segment or any extended data segment.
Syntax for C Programmers #include short FILE_WRITEUPDATE64_ ( short filenum ,const char _ptr64 *buffer ,__int32_t write-count ,[ __int32_t _ptr64 *count-written ] ,[ long long tag ] ); Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_WRITEUPDATE64_) error := FILE_WRITEUPDATE64_ ( filenum ,buffer ,write-count ,[ count-written ] ,[ tag ] ); ! ! ! ! ! i i i o i Parameters filenum input INT:value is a number of an open file that identifies the file to be w
NOTE: The system stores the tag value until the I/O operation completes. It then returns the tag information to the program in either the tag parameter of the call to FILE_AWAITIO64_ or the tag field of the completion-info parameter of the call to FILE_COMPLETEL_, thus indicating that the operation finished. Returned Value INT A file-system error code that indicates the outcome of the call. 22 • The segment is in use at the time of the call or the segment in use is invalid.
the Transaction Management Facility (TMF), the FILE_AWAITIO64_ or FILE_COMPLETEL_ procedure must be called before the ENDTRANSACTION or ABORTTRANSACTION procedure is called. WARNING! When using nowait file I/O, data corruption might occur if the READ or WRITE buffers are modified before the FILE_AWAITIO64_ or FILE_COMPLETEL_procedure completes the call. The buffer space must not be freed or reused while the I/O is in progress.
maximum PFS size is 32 MB. This limits the number of concurrent no-wait operations with large read-count or write-count values. Perform the following steps to work around this limit: 1. Define the read and write buffers with sizes in multiples of 16KB. 2. Call the USERIOBUFFER_ALLOW_ procedure before making any calls to these procedures. 3. Allocate extended data segments using the SEGMENT_ALLOCATE64_ procedure. 4. Define a pool on the segment using the POOL64_DEFINE_ procedure. 5.
You set the odd unstructured attribute with the FILE_CREATE_, FILE_CREATELIST_, or CREATE procedure, or with the File Utility Program (FUP) SET and CREATE commands. • Structured files ◦ Calling FILE_WRITEUPDATE64_ after FILE_SETKEY_ (or KEYPOSITION[X]) If the call to FILE_WRITEUPDATE64_ immediately follows a call to FILE_SETKEY_ (or KEYPOSITION[X]) in which a nonunique alternate key is specified as the access path, FILE_WRITEUPDATE64_ fails with error 46 (invalid key).
Related Programming Manuals For programming information about the FILE_WRITEUPDATE64_ procedure, see the Enscribe Programmer's Guide and the Guardian Programmer's Guide.
FILE_WRITEUPDATEUNLOCK64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_WRITEUPDATEUNLOCK64_ procedure is used for random processing of records in a disk file. The data buffer for FILE_WRITEUPDATEUNLOCK64_ can be either in the caller's stack segment or any extended data segment.
Syntax for TAL Programmers ?SETTOG _64BIT_CALLS ?SOURCE EXTDECS(FILE_WRITEUPDATEUNLOCK64_) error := FILE_WRITEUPDATEUNLOCK64_ ( filenum ,buffer ,write-count ,[ count-written ,[ tag ] ); ! ! ! ] ! ! i i i o i Parameters filenum input INT:value is a number of an open file that identifies the file to be written. buffer input STRING .EXT64:ref:* is an array that contains the data to be written to the file. write-count input INT(32):value is the number of bytes to be written to the file: {0:4096}.
Returned Value INT A file-system error code that indicates the outcome of the call. 22 • The address of a parameter is extended, but no segment is in use at the time of the call or the segment in use is invalid. • The address of a parameter is extended, but it is an absolute address and the caller is not privileged. • The file system cannot use the user's segment when needed.
• Record does not exist Positioning for FILE_WRITEUPDATEUNLOCK64_ is always to the record described by the exact value of the current key and current-key specifier. Therefore, if such a record does not exist, the call to FILE_WRITEUPDATEUNLOCK64_ is rejected with file-system error 11. See the FILE_WRITEUPDATE64_ procedure Considerations (page 538). • Invalid write operations to queue files DP2 rejects FILE_WRITEUPDATEUNLOCK64_ operations to queue files with an error 2.
4. 5. Define a pool on the segment using the POOL64_DEFINE_ procedure. Allocate buffers from the pool boundaries. See the FILE_AWAITIO64_ procedure for an example. On non-NSAA systems, reads and writes larger than 4KB on key-sequenced files may be performed directly from or into the application’s buffer. OSS Considerations This procedure operates only on Guardian objects. If an OSS file is specified, error 2 is returned.
FILEERROR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The FILEERROR procedure is used to determine whether an I/O operation that completed with an error should be retried.
Considerations The FILEERROR procedure is called after a CCL return from a file-system procedure. The FILEERROR procedure determines if an operation should or should not be retried. • If the error is caused by one of these: ◦ A normal access request to a terminal currently in BREAK mode ◦ BREAK key typed on a terminal where BREAK is enabled ◦ Disk pack not up to speed FILEERROR delays the calling process for one second and then returns a 1, indicating a retry should be performed.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Examples Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FILEINFO procedure obtains error and characteristic information about a file.
Parameters filenum input INT:value is the number of an open file that identifies the file whose characteristics are to be returned. Either filenum or file-name must be specified; if both are passed, then file-name is set to the file name associated with filenum. If filenum is not specified, error 2 is returned for non-disk files. error output INT:ref:1 returns the error number associated with the last operation on the file.
Note the following behavior for partitioned files: • If a partition is not open, the associated ldevnum field returns a value of -1. • If a logical device number to be returned is greater than 65375, the associated ldevnum field is set to 32767, and 0 is returned in error. • In H06.28/J06.17 RVUs with specific SPRs and later RVUs, if an enhanced key-sequenced file has 17 to 128 partitions, each of the 16 elements in the ldevnum array are set to the value 32767, and 0 is returned in error.
last-modtime output INT:ref:3 for disk files only, returns a three-word timestamp indicating the last time the file was modified; if the file has never been modified, its creation time is returned. last-modtime is of the same form as the interval-clock returned by TIMESTAMP and can be converted into a date by CONTIME. You can obtain the same information in a four-word timestamp by calling FILEINQUIRE.
<6> 1 Indicates that resident buffers are provided by the application process for calls to file system I/O routines. A 0 is always returned in this bit (see OPEN Procedure (Superseded by FILE_OPEN_ Procedure) (page 897)). <8> 1 For process files means that the open message is to be sent nowait and must be completed by a call to AWAITIO. <9> 1 Specifies that this is a queue file.
In security[1:4], the returned values are: Returned Value 0 1 2 3 4 5 6 7 Security Level A G O n/a N C U Super num-extents-allocated output INT:ref:1 returns the number of extents that are allocated for the file. This parameter is invalid with filenum; use file-name. max-file-size output INT(32):ref:1 returns the maximum number of bytes configured for the file. This parameter is invalid with filenum; use file-name.
7 File is an SQL shorthand view. <9> 1 For interrogating queue files. <10> 1 Indicates REFRESH is specified for this file. <11> 1 For key-sequenced files, indicates index compression is specified. <12> 1 For key-sequenced files, indicates data compression is specified. 1 For key-sequenced files, indicates data compression is specified.
<9> <10> 1 Licensed to have privileged procedures. 0 Not a secondary partition of a partitioned file. 1 Is a secondary partition of a partitioned file. 0 File contents are valid. 1 File contents are probably invalid because a FUP DUP or LOAD, RESTORE, or similar operation ended abnormally. When this bit is 1, OPEN fails with error 59, although PURGE will work. <11:15> Reserved.
Table 21 FILEINFO filenum and file-name Parameters (continued) Parameter File Number File Name , [ current-record-pointer ] X X , [ open-flags2 ] X , [ subdev ] X , [ owner ] X , [ security ] X , [ num-extents-allocated ] X , [ max-file-size ] X , [ partition-size ] X , [ num-partitions ] X , [ file-type ] X , [ maximum-extents ] X X , [ unstructured-buffer-size ] X X , [ more-flags ] X X , [ sync-depth ] X , [ next-open-fnum ] X Condition Code Settings < (CCL) indicate
13 Invalid file name 14 Device does not exist 249 Access to the system specified in file-name failed 250 The system specified in file-name is not part of the network In general, to obtain information about errors relating to operations on open files (including failures to open a file), use the file number form of this request. For information about files that do not have to be opened, use the file name form.
FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Item Codes Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FILEINQUIRE procedure is used to obtain items of information about a file.
number-items input INT:value is the number of items in item-list. result-buffer output INT .EXT:ref:* is the array in which the requested information items are returned. The items are returned in the order specified in item-list. Each item begins on an INT boundary; if the preceding item had a length of an odd number of bytes then an used byte will occur between the items. The length of each item is given in Table 22 (page 562).
Item Codes Table 22 describes the item codes used by FILEINQUIRE. It includes their size and whether the item is valid when the procedure is called with filenumber, file-name, or both. Table 22 FILEINQUIRE Item Codes Code Size (bytes) Valid with Number/Name Description 1 6 num For labeled tapes, the tape volume serial number of the reel currently being processed. 2 24 num DEFINE name which was opened. Not valid for files which were opened without use of a DEFINE.
Table 22 FILEINQUIRE Item Codes (continued) Code Size (bytes) Valid with Number/Name Description the time of its creation is returned. This is the same information as available through FILEINFO in three-word TIMESTAMP form. 17 4 num For particular access methods on some devices, a value associated with the last completed I/O operation. The meaning of the value is specific to the access method. For SNAX, it is the exception response identification number.
FILENAME_COMPARE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The FILENAME_COMPARE_ procedure compares two file names to determine whether they refer to the same object.
Returned Value INT Outcome of the call: -1 The file names do not refer to the same object. 0 The file names refer to the same object. >0 A file-system error prevented evaluation; the returned value is the file-system error code. Considerations CAUTION: Passing an invalid file name to this procedure can result in a trap, a signal, or data corruption. To verify that a file name is valid, use the FILENAME_SCAN_ procedure. • The name comparison is not case sensitive.
FILENAME_DECOMPOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary The FILENAME_DECOMPOSE_ procedure extracts and returns one or more parts of a file name or file-name pattern.
piece-length output INT .EXT:ref:1 returns the length in bytes of the extracted piece of filename. If an error occurs, 0 is returned. level input INT:value specifies a part of filename. Together with options and subpart, it defines the piece of filename to be returned.
Returned Value INT A file-system error code that indicates the outcome of the call. Considerations CAUTION: Passing an invalid file name or file-name pattern to this procedure can result in a trap, a signal, or data corruption. To verify that a file name or file-name pattern is valid, use the FILENAME_SCAN_ procedure. • When the FILENAME_DECOMPOSE_ procedure returns a portion of a file name, it does not include leading or trailing separators (the characters . :).
FILENAME_EDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary The FILENAME_EDIT_ procedure modifies one or more parts of a file name or file-name pattern, changing them to a specified value.
filename-length input, output INT .EXT:ref:1 on input, is the length in bytes of the name to be edited; on output, is the length in bytes of the edited version of the file name. piece:length input:input STRING .EXT:ref:*, INT:value specifies the string that is to replace the portion of filename that is indicated by the parameters that follow. If used, the value of piece must be exactly length bytes long. If length is 0, the indicated portion of filename is deleted. See Considerations.
NOTE: The sequence number is mandatory for unnamed processes. Do not remove the sequence number from an unnamed process file name because a fatal error will result. 4 Replace name, that is, the alphanumeric section that begins with a question mark and ends at the first colon or period. The default value is 0. You should specify a nonzero value for subpart only when level is 0 and bits 14 and 15 (extract prefix and extract suffix) of options are 0.
Examples This table shows some possible combinations of input values for calls to FILENAME_EDIT_ and the resulting output values. Note that "suffix" refers to the "replace suffix" option in options, and "name" refers to a subpart value of 4. Assume that the current default values are "\SYS.$VOL.SUB". Input filename piece level Modifiers Output filename $a.b.c * 1 $a.b.c * 1 $s #mfile 1 $s.#mfile f x 1 x.f f $x 0 $x.SUB.f f \s -1 \s.$VOL.SUB.f $p:4321.#a $z 0 $a.*.
FILENAME_FINDFINISH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Related Programming Manual Summary The FILENAME_FINDFINISH_ procedure releases the resources reserved for a search that was previously initiated by a call to FILENAME_FINDSTART_.
FILENAME_FINDNEXT[64]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Nowait Considerations Related Programming Manual Summary The FILENAME_FINDNEXT_ procedure returns the next name in a set of named entities that was defined by a call to the FILENAME_FINDSTART_ procedure. FILENAME_FINDNEXT64_ is a 64–bit version of the FILENAME_FINDNEXT_ procedure.
• The parameter maxlen specifies the maximum length in bytes of the character string pointed to by name. The actual length of name in name is returned in name-length. These three parameters must either all be supplied or all be absent.
if present, returns a block of five words that might contain information about the entity designated by name. Note that some of the fields do not apply to all kinds of entities. (None of them apply to nodes.) The fields are: [0] Device type. [1] Device type. [2:4] Device-specific information. When the device type is 3 (disk), the meanings are: [2] Object type. If greater than 0, this is an SQL object; if equal to 0, this is a non-SQL disk file; if equal to -1, this is an entire volume or subvolume.
In general, it is not worthwhile to retry errors that do not return a name, because the condition that caused the error is likely to recur. For files residing on Storage Management Foundation (SMF) virtual disks, call FILE_GETINFOLISTBYNAME_ after the file name is returned by FILENAME_FINDNEXT[64]_. Without the additional call, FILENAME_FINDNEXT[64]_ will always return 0 as object type. Nowait Considerations • If you specify the nowait option (options.
FILENAME_FINDSTART_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Device Type Considerations Error Handling Example Related Programming Manual Summary The FILENAME_FINDSTART_ procedure sets up a search of named entities. After specifying search criteria to FILENAME_FINDSTART_, you call the FILENAME_FINDNEXT[64]_ procedure to retrieve individual names.
search-pattern:length input:input STRING .EXT:ref:*, INT:value if supplied and if length is not 0, contains a valid file-name pattern that specifies the set of names to be searched. If used, the value of search-pattern must be exactly length bytes long. A partially qualified file-name pattern is resolved using the contents of the caller's =_DEFAULTS DEFINE. "*" is the default search pattern. For the definition of file-name pattern, see Appendix D: File Names and Process Identifiers.
options input INT:value specifies further options. The bits, when equal to 1, indicate: Bit Meaning <0:7> Reserved (specify 0). <8> If a physical file corresponding to a NonStop Storage Management Foundation (SMF) logical file is encountered, the name of the physical file is to be returned. <9> The search is to be executed in a nowait manner.
to fail with error 34.) When finished searching, you should call FILENAME_FINDFINISH_ with searchid to release the resources. • The file-name pattern supplied in search-pattern determines the kind of names that will be returned by FILENAME_FINDNEXT[64]_ and also restricts the range of name values. For example, \* will return node names; $* will return device names and process file names. Subvolume names can be retrieved with file-name patterns such as $VOL.*.
• The system allows certain processes, which are distinguished by having a device subtype of 30, to simulate device types. During a file name search, these processes are normally sent a system message inquiring about the device-type and subtype values they present. The result of this inquiry is used for selection under the device-type and device-subtype selection criteria and for information reporting by FILENAME_FINDNEXT[64]_. You can suppress device type simulation by specifying options.<10> = 1.
FILENAME_MATCH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary The FILENAME_MATCH_ procedure determines whether one or more contiguous sections of a file name match the corresponding sections of a file-name pattern (that is, whether the file name sections might be represented by the pattern sections). FILENAME_MATCH_ does not resolve partially qualified file names.
generic-set output INT .EXT:ref:1 if status is 0, returns a value indicating whether filename is a member of, falls before, or falls after the generic set of names defined by pattern. A name is part of the generic set if it matches pattern up to the first wild-card character (* or ?). Valid values are: -1 The name falls before the first possible match. 0 The name falls within the set of possible matches. 1 The name falls after the last possible match.
Examples result := FILENAME_MATCH_ ( filename:flen, pattern:plen ); This table shows some possible combinations of input parameters and the corresponding values of status for the foregoing call to FILENAME_MATCH_: filename pattern status generic-set cab.ride C*B.* 2 (match) N/A cab c*b.* 1 (partial match) N/A bable c*b.* 0 (no match) -1 (before set) c c*b.* 0 (no match) 0 (part of set) czz.ride c*b.* 0 (no match) 0 (part of set) d c*b.
FILENAME_RESOLVE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The FILENAME_RESOLVE_ procedure converts a partially qualified file name to a fully qualified file name. You can supply a search list when qualifying a disk file name. You can also use FILENAME_RESOLVE_ to resolve absent sections of a file-name pattern or to resolve a DEFINE that contains a file name and can be opened.
Parameters partialname:length input:input STRING .EXT:ref:*, INT:value is a valid, partially qualified file name or file-name pattern that is to be resolved. partialname can also be a valid DEFINE name (see the description of the options parameter). The value of partialname must be exactly length bytes long. See caution under Considerations. fullname:maxlen output:input STRING .EXT:ref:*, INT:value contains the resulting fully qualified file name.
Bit Meaning <12> If a DEFINE name is supplied for partialname, and if the DEFINE contains only a file name (that is, it is a simple MAP DEFINE), then FILENAME_RESOLVE_ returns that file name as the result. (Error 198 is returned if the DEFINE doesn't exist; error 13 is returned if DEFMODE is OFF.) If neither this option nor options.<11> is specified, then the DEFINE name is returned as the result.
Considerations CAUTION: Passing an invalid file name or file-name pattern to this procedure can result in a trap, a signal, or data corruption. To verify that a file name or file-name pattern is valid, use the FILENAME_SCAN_ procedure. • FILENAME_RESOLVE_ performs the principal steps of its operation in this order. 1. If the caller supplied the name of an existing DEFINE in override-name, it substitutes the DEFINE name for partialname. 2. If the criteria for doing a search are met, it performs a search. 3.
Example In the following example, name is resolved using a search list if the DEFINE =SRCHLST exists; if the DEFINE does not exist, name is resolved by normal means. slist ':=' "=SRCHLST"; error:= FILENAME_RESOLVE_( name:namelen, outname:256, outnamelen, , , slist:8 ); Related Programming Manual For programming information about the FILENAME_RESOLVE_ procedure, see the Guardian Programmer's Guide.
FILENAME_SCAN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The FILENAME_SCAN_ procedure checks for valid file-name syntax and returns the length in bytes of that part of the input string that constitutes a file name. Node names are accepted as valid input, as are partially or fully qualified names of disk files, processes, and devices.
count output INT .EXT:ref:1 is the number of characters occupied by the name if a valid name is found. If error 13 is returned in error, count contains the number of characters examined when the name was determined to be invalid. To know that the entire input string constitutes a valid name, you should verify that count is equal to length. See Example. kind output INT .EXT:ref:1 identifies the class of name that was found. Possible values are: 0 File name (that is, the name of an entity).
Returned Value INT A file-system error code that indicates the outcome of the call: 0 Syntactically correct name found for count; see description of count parameter. 13 The form of the name found is incorrect; also, various program and resource errors. Considerations • The syntax checking performed by FILENAME_SCAN_ includes checks that the lengths of individual name parts are acceptable. (For example, it checks that a subvolume name is no more than 8 characters long.
FILENAME_TO_OLDFILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The FILENAME_TO_OLDFILENAME_ procedure converts a file name to the C-series internal file-name format. See Appendix D: File Names and Process Identifiers for descriptions of C-series and D-series file names.
Considerations CAUTION: Passing an invalid file name to this procedure can result in a trap, a signal, or data corruption. To verify that a file name is valid, use the FILENAME_SCAN_ procedure. • The process file name of an unnamed process can be converted if it has a PIN of 255 or less. • If filename contains a node name or if the default node name is remote, oldstyle-name is normally returned in internal network form. Otherwise, oldstyle-name is in internal local form.
FILENAME_TO_PATHNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value OSS Considerations Example Related Programming Manual Summary The FILENAME_TO_PATHNAME_ procedure converts a Guardian file name or subvolume name to an OSS pathname. See Appendix D: File Names and Process Identifiers for a descriptions of OSS pathname syntax.
pathlen output INT .EXT:ref:1 returns the actual length in bytes of the pathname parameter, including the terminating null character. options input INT:value specifies options for the filename parameter: <0:12> Reserved (specify 0). <13> <14> <15> 1 If the caller has appropriate privileges, specifies that pathname is an absolute pathname with respect to the system root. 0 Specifies that pathname is an absolute pathname with respect to the current root of the process.
• When resolving multiple pathames to a file, index does not correspond to a pathname of the file. • options.<13> = 0, options.<14> = 1 and a chroot() function was executed which changed the root to something other than “/.” The corresponding OSS errno value is EINVAL. 4202 The root fileset is not mounted. The corresponding OSS errno value is ENOROOT. 4211 The resulting pathname is longer than the limit defined in PATH_MAX. (PATH_MAX is a symbolic constant defined in the OSS limits.h header file.
Example ret = FILENAME_TO_PATHNAME_(argv[1], /* Guardian file name */ (short)strlen(argv[1]), /* length of file name */ pathname, /* buffer for OSS path name */ PATH_MAX, /* length of buffer */ &pathlen, /* length of path name */ , ); Related Programming Manual For programming information about the FILENAME_TO_PATHNAME_ procedure, see the Open System Services Programmer's Guide.
FILENAME_TO_PROCESSHANDLE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The FILENAME_TO_PROCESSHANDLE_ procedure converts a file name to a process handle.
Considerations CAUTION: Passing an invalid file name to this procedure can result in a trap, a signal, or data corruption. To verify that a file name is valid, use the FILENAME_SCAN_ procedure. • If the file name to be converted by FILENAME_TO_PROCESSHANDLE_ designates something besides a process (for example, a disk file or a tape device), the procedure returns the process handle of the process that controls the device (that is, the I/O process).
FILENAME_UNRESOLVE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary The FILENAME_UNRESOLVE_ procedure accepts a file name as input, deletes left-hand sections that match the default values, and returns a file name that is semantically equivalent to the input file name.
shortname:maxlen output:input STRING .EXT:ref:*, INT:value defines the buffer where the resultant file name is to be placed. This buffer can occupy the same area as longname. The length of the resultant name is never greater than the length of longname. maxlen is the length in bytes of the string variable shortname. shortname-length output INT .EXT:ref:1 returns the length in bytes of the name returned in shortname. If an error occurs, 0 is returned.
Considerations CAUTION: Passing an invalid file name or file-name pattern to this procedure can result in a trap, a signal, or data corruption. To verify that a file name or file-name pattern is valid, use the FILENAME_SCAN_ procedure. • The FILENAME_UNRESOLVE_ procedure compares a specified file name with the default subvolume specification and removes left-hand sections that are identical.
FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FILERECINFO procedure obtains record characteristics of a disk file.
current-keyvalue output STRING:ref:* returns the value of the current key for current-keylen bytes. This parameter is invalid when you specify the file-name parameter; use filenum. This parameter is not valid for queue files. Also, this parameter cannot be used with a non-key-sequenced file opened with 64-bit primary keys open flag. If an attempt is made, the call will fail with condition code CCL. current-keylen output INT:ref:1 returns the current key length in bytes.
file-type output INT:ref:1 returns a number indicating the type of file being accessed. <2> 1 For systems with the Transaction Management Facility, indicates this file is audited. Specifies object type for SQL object file: <5:7> 0 File is not SQL. 2 File is an SQL table. 4 File is an SQL index. 5 File is an SQL protection view. 7 File is an SQL shorthand view. <9> 1 Specifies that this is a queue file. <10> 1 Means REFRESH is specified for this file.
partition-parameters output INT:ref:* is an array where the parameters describing a multivolume file are returned. For the format of the array, see the description of the partition-parameters parameter in the CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure) (page 228). In H06.28/J06.17 RVUs with specific SPRs and later RVUs, the array for an enhanced key-sequenced file can contain up to 127 elements. (For a list of the required H06.28/J06.
Example CALL FILERECINFO ( FILE^NUMBER , ! , ! , ! , ! , ! , ! , ! ,FILE^TYPE ); current key specifier. current key value. current key length. current primary key value. current primary key length. partition in error. key in error.
FIXSTRING Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manual Summary The FIXSTRING procedure is used to edit a string based on subcommands provided in a template.
The form of template is: template={ subcommand // ... }template = { subcommand // ... } subcommand = { { { { Rreplacement string Iinsertion string D replacement string } } } } ! ! ! ! replace subcommand insert subcommand delete subcommand implicit replacement template-len input INT:value is the length, in bytes, of the template string. data input, output STRING:ref:* on input, is a string to be modified. The resulting string returns in this parameter.
Note that a subcommand may immediately follow "D" without being preceded by "//." If a subcommand begins with "R," "I," or "D," it is recognized as an explicit command. Otherwise, it is recognized as an implied replacement. The action of the subcommands is as follows: ◦ R (or r) for "replace" This subcommand replaces characters in data with replacement-string on a one-for-one basis. Replacement begins with the character corresponding to R.
FNAMECOLLAPSE Procedure (Superseded by OLDFILENAME_TO_FILENAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAMECOLLAPSE procedure converts a file name from internal to external form. The system number of a network file name is converted to the corresponding system name.
Considerations • Invalid file names It is the responsibility of the program calling FNAMECOLLAPSE to pass a valid file name in internal-name. Invalid file names cause unpredictable results such as retrieving information from the wrong file. • Passing a bad sysnum value If internal-name is in network form, and the system number in the second byte does not correspond to any system in the network, FNAMECOLLAPSE supplies "??" as the system name.
FNAMECOMPARE Procedure (Superseded by FILENAME_COMPARE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAMECOMPARE procedure compares two file names within a local or network environment to determine whether these file names refer to the same file or device.
Returned Value INT A status value indicating the outcome of the comparison: -1 The file names do not refer to the same file. 0 The file names refer to the same file. 1 The file names refer to the same volume name, device name, or process name on the same system; however, words [4:11] are not the same: filename1[4] <> filename2[4] FOR 8 A value less than -1 is the negative of a file-system error code; in these cases, the comparison is not attempted.
Examples On system number 6, execution of: FNAME1 ':=' [ "$TERM1" , 9 * [ " "] ]; FNAME2 ':=' [ %56006 , "TERM1 " , 8 * [ " "] ]; ! "\ , "TERM1"; STATUS := FNAMECOMPARE ( FNAME1 , FNAME2 ); returns a 0 in STATUS. On other systems, execution of the example returns a status of -1. Whether a system is a network node or not, execution of: FNAME1 ':=' [ "$SERVR #START UPDATING" ]; FNAME2 ':=' [ "$SERVR #FINISH UPDATING" ]; STATUS := FNAMECOMPARE ( FNAME1 , FNAME2 ); returns a status of +1.
FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and FILENAME_RESOLVE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAMEEXPAND procedure is used to expand a partial file name from the compacted external form to the standard 12-word internal form usable by other file-system procedures.
internal-filename output INT:ref:12 is an array of 12 words where FNAMEEXPAND returns the expanded file name. FNAMEEXPAND (unlike FNAMECOLLAPSE) can have the same source and destination buffers (file names) since it uses a temporary intermediate storage area for the conversion. (See Considerations for the form of the returned internal-filename.) default-names input INT:ref:8 is an array of eight words containing the default volume and subvolume names to be used in file name expansion.
• • • • • $volname.file-id returns as: [0:3] $default-volname (blank-fill) [4:7] default-subvolname (blank-fill) [8:11] file-id (blank-fill) $volname.subvolname.file-id returns as: [0:3] $default-volname (blank-fill) [4:7] default-subvolname (blank-fill) [8:11] file-id (blank-fill) $processname.#1st-qualif-name returns as: [0:3] $processname (blank-fill) [4:7] #1st-qualif-name (blank-fill) [8:11] (blank-fill) $processname.#1st-qualif-name.
FNAMETOFNAME32 Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAMETOFNAME32 procedure converts a file name from the 12-word internal format to the 32-character Distributed Name Service (DNS) format.
Related Programming Manual For network programming applications, see the Distributed Name Service (DNS) Manual.
FNAME32COLLAPSE Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAME32COLLAPSE procedure converts the 32-character file name used by the Distributed Name Service to external format for display.
Related Programming Manual For network programming applications, see the Distributed Name Service (DNS) Manual.
FNAME32EXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAME32EXPAND procedure expands a partial file name from the compacted external form to the 32-character file name used by the Distributed Name Service (DNS) programmatic interface.
defaults input STRING .EXT:ref:16 or 18 is an array of eight words containing the default volume and subvolume name (and optionally system number) that is to be used in the file name expansion. This array has the same format as the corresponding parameter to FNAMEEXPAND. Or it is an array of nine words where the first word contains the default system number and the remaining eight words contain the default volume and subvolume names.
FNAME32TOFNAME Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The FNAME32TOFNAME procedure converts a file name from the 32-character format used by the Distributed Name Service (DNS) to its internal format.
Considerations • If a parameter is missing or if a bounds error occurs on a parameter, 0 is returned. • If the first eight characters of fname32 contain the name of the system on which the procedure is called, fname is returned in local format.
FORMATCONVERT[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The FORMATCONVERT and FORMATCONVERTX procedures convert a format (a data record layout described by means of edit descriptors) from external form to the internal form that is required for presentation to the FORMATDATA[X] procedures.
Parameters iformat output STRING:ref:* (for FORMATCONVERT) STRING .EXT:ref:* (for FORMATCONVERTX) is an array in which FORMATCONVERT[X] stores the converted format. The contents of this array must be passed to the FORMATDATA[X] procedure as an integer parameter, but FORMATCONVERT requires it to be in byte-addressable G-relative storage. Thus iformat must be aligned on a word boundary, or the contents of iformat must be moved to a word-aligned area when it is passed to FORMATDATA[X].
scale-count input, output INT:ref:* (for FORMATCONVERT) INT .EXT:ref:* (for FORMATCONVERTX) on call, is the number of occurrences of the scales array. On return, scale-count contains the actual number of repeatable edit descriptors converted.
FORMATDATA[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary NOTE: The FORMATDATA procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. Use the FORMATDATAX procedure.
Syntax for TAL Programmers error := FORMATDATA[X] ( buffer ,bufferlen ,buffer-occurs ,length ,iformat ,variable-list ,variable-list-len ,flags ); ! ! ! ! ! ! ! ! i,o i i o i i i i Parameters buffer input, output STRING:ref:* (for FORMATDATA) STRING .EXT:ref:* (for FORMATDATAX) is a buffer or a series of contiguous buffers where the formatted output data is placed or where the input data is found. The length, in bytes, of buffer must be at least bufferlen * buffer-occurs.
variable-list input INT:ref:* (for FORMATDATA) INT .EXT:ref:* (for FORMATDATAX) is a four- to seven-word entry for each array or variable. See Considerations (page 635) for the contents and form of this array. variable-list-len input INT:value is the number of variable-list entries passed in this call. flags input INT:value Bit Values <15> Input 0 FORMATDATA[X] performs output operations. 1 FORMATDATA[X] performs input operations.
271 EDIT item mismatch. 272 Invalid input character. 273 Bad format. 274 Numeric overflow. Considerations • A passed P-relative iformat array must be in the same code segment as the call.
15 Numeric string, sign leading, separate 16 Not used 17 Logical * 1 (1 byte) 18 Not used 19 Logical * 2 (INT(16)) 20 Not used 21 Logical * 4 (INT(32)) 22 Integer(8) signed 23 Integer(8) unsigned Data types 7 through 11 require floating-point firmware. bits <0:7> Scale factor moves the position of the implied decimal point by adjusting the internal representation of the expression.
FP_IEEE_DENORM_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Summary The FP_IEEE_DENORM_GET_ procedure reads the IEEE floating-point denormalization mode. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-series systems, except S70000 servers with NSR-G processors. Syntax for C Programmers #include
FP_IEEE_DENORM_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The FP_IEEE_DENORM_SET_ procedure sets the IEEE floating-point denormalization mode. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-Series systems, except S70000 servers with NSR-G processors. Syntax for C Programmers #include
FP_IEEE_ENABLES_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary The FP_IEEE_ENABLES_GET_ procedure reads the IEEE floating-point trap enable mask. A set bit (value of one) means that the trap for that particular exception is enabled. A zero bit means that it is disabled. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06.
• Trap handling is an optional part of the IEEE floating-point standard. See the FP_IEEE_EXCEPTIONS_GET_ Procedure (page 646) and the FP_IEEE_EXCEPTIONS_SET_ Procedure (page 648) for an alternative to using traps. • The compiler optimizer might reorder operations within a local routine and cause different results from the FP_ IEEE status procedures than intended. To work around this, place arithmetic operations in a separate function.
FP_IEEE_ENABLES_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Examples Summary The FP_IEEE_ENABLES_SET_ procedure sets the IEEE floating-point trap enable mask. A set bit (value of one) enables a trap for the particular exception. A zero bit (the normal value) disables that trap. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06.
Examples C Example #include void TrapsEnableExample(void) { FP_IEEE_ENABLES_SET_ ( FP_IEEE_ENABLE_INVALID | FP_IEEE_ENABLE_DIVBYZERO| FP_IEEE_ENABLE_OVERFLOW ); } This sets traps on the FP_IEEE_INVALID, FP_IEEE_DIVBYZERO, and FP_IEEE_OVERFLOW exceptions. TAL Example ?nolist ?source $system.system.
FP_IEEE_ENV_CLEAR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Examples Summary The FP_IEEE_ENV_CLEAR_ procedure sets the floating-point environment (consisting of the rounding mode, the exception flags, the trap enables, and the denormalization mode) back to its initial values.
Examples C Example #include void TotalEnvExample(void) { fp_ieee_env previousEnv; previousEnv = FP_IEEE_ENV_CLEAR_(); /*restore initial env*/ Do_Computation(); FP_IEEE_ENV_RESUME_( previousEnv ) /*restore previous env*/ } TAL Example proc DOCOMPUTATION; external; ?nolist ?source $system.system.
FP_IEEE_ENV_RESUME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Examples Summary The FP_IEEE_ENV_RESUME_ procedure restores the floating-point environment (the rounding mode, the exception flags, the trap enables, and the denormalization mode) to the values it had before calling FP_IEEE_ENV_CLEAR_. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06.
FP_IEEE_EXCEPTIONS_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Examples Summary The FP_IEEE_EXCEPTIONS_GET_ procedure reads the IEEE floating-point exception mask. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-Series systems, except S70000 servers with NSR-G processors.
Examples C Example #include void Example(void) { FP_IEEE_EXCEPTIONS_SET_( 0 ); /* clear exceptions */ DoComputation(); /* floating-point computation */ if( FP_IEEE_EXCEPTIONS_GET_() & (FP_IEEE_INVALID|FP_IEEE_OVERFLOW|FP_IEEE_DIVBYZERO) ) printf( "Trouble in computation! \n" ); } TAL Example proc DOCOMPUTATION; external; ?nolist ?source $system.system.
FP_IEEE_EXCEPTIONS_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Examples Summary The FP_IEEE_EXCEPTIONS_SET_ procedure sets the IEEE floating-point exception mask. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-Series systems, except S70000 servers with NSR-G processors.
Examples For examples of the use of this call, see the FP_IEEE_EXCEPTIONS_GET_ procedure Examples (page 647).
FP_IEEE_ROUND_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Summary The FP_IEEE_ROUND_GET_ procedure reads the current rounding mode. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-Series systems, except S70000 servers with NSR-G processors. Syntax for C Programmers #include
FP_IEEE_ROUND_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Summary The FP_IEEE_ROUND_SET_ procedure sets the current rounding mode. NOTE: This procedure is supported in all J-series and H-series RVUs and in G-series RVUs beginning with G06.06. IEEE floating-point is available on all NB-Series and NS-Series systems, and on all S-Series systems, except S70000 servers with NSR-G processors. Syntax for C Programmers #include
6 Guardian Procedure Calls (G) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter G. Table 23 lists all the procedures in this section.
GETCPCBINFO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary The GETCPCBINFO procedure provides a process with information from its own (the current) process control block (PCB).
The bits are defined as follows: <0:8> (reserved) <9> Propagate stop-on-logoff <10> Propagate logon <11> Stop on logoff <12> Inherited logon <13> Safeguard-authenticated logoff state <14> Safeguard-authenticated logon <15> Logged-on state cpcb-info output INT:ref:* is an array that returns with the information requested from the PCB. in-length input INT:value specifies the length, in bytes, of the cpcb-info array. (This is used to prevent possible data overrun.
GETCRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The GETCRTPID procedure is used to obtain the four-word CRTPID (which contains the process name or creation timestamp in words [0:2] and cpu,pin in word [3]) associated with a process.
Condition Code Settings < (CCL) indicates that GETCRTPID failed, or that no such process exists, or that the process exists but it is terminating. = (CCE) indicates that GETCRTPID completed successfully. > (CCG) does not return from GETCRTPID. Considerations • Passing the process ID to OPEN The process ID returned from GETCRTPID is suitable for passing directly to the file-system OPEN procedure (if expanded to 12 words and blank-filled on the right).
GETDEVNAME Procedure (Superseded by FILENAME_FINDNEXT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The GETDEVNAME procedure obtains the name associated with a logical device number.
devices that match the specified parameters satisfy the search. The range of valid logical device number input values is 0 through 65375. You can also specify a starting value of 65535 to request a search starting with the lowest-numbered logical device in the system. This alternative is equivalent to specifying a starting value of 0, and is provided only for compatibility with previous RVUs. On return, ldevnum receives the number of the first matching logical device, if one exists.
4 The system specified could not be accessed. 99 Parameter error. Considerations • The device name is returned in network form whenever the sysnum parameter is supplied (except when the local system number is specified). • If the sysnum parameter is supplied, devices whose names contain seven characters are not accessible using this procedure. This is because internal-form network names are limited to six characters.
GETINCREMENTEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The GETINCREMENTEDIT procedure returns the record number increment value for an IOEdit file. GETINCREMENTEDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
GETPOOL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Considerations Example Related Programming Manual Summary The GETPOOL procedure obtains a block of memory from a buffer pool initialized by the DEFINEPOOL procedure. Syntax for C Programmers You cannot call GETPOOL directly from a C program, because it returns a value and also sets the condition-code register.
Returned Value EXTADDR The extended address of the memory block obtained if the operation is successful, or -1D if an error occurred or block-size is 0. (Values less than -1D may be returned to privileged callers.) CAUTION: The address must be a simple INT(32) or EXTADDR variable; otherwise, the assignment can alter the condition code. Considerations • For performance reasons in the operating system, GETPOOL and PUTPOOL do not check pool data structures on each call.
GETPOOL_PAGE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Summary The GETPOOL_PAGE_ procedure obtains a block of memory from a buffer pool. The memory is aligned on a page boundary and the space allocated is a multiple of a page size. The GETPOOL_PAGE_ procedure is supported only in J-series and H-series RVUs.
Returned Value EXTADDR The extended address of the memory block obtained if the operation is successful, or -1D if an error occurred or block-size is 0. (Values less than -1D may be returned to privileged callers.) CAUTION: The address must be a simple INT(32) or EXTADDR variable; otherwise, the assignment can alter the condition code.
GETPOSITIONEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Related Programming Manual Summary The GETPOSITIONEDIT procedure returns the record number (1000 times the EDIT line number) of the line in the specified file most recently read or written (that is, it returns the current record number). GETPOSITIONEDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
GETPPDENTRY Procedure (Superseded by PROCESS_GETPAIRINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The GETPPDENTRY procedure is used to obtain a description of a named process pair by its index into the destination control table (DCT).
[4].<8:15> PIN of backup process, if it is a process pair. (This is 0 if there is no backup.) [5:8] process-id of ancestor. Note that the process-id is a 4- word array of this form: [0:2] Process name or creation timestamp [3].<0:3> Reserved [3].<4:7> Processor number where the process is executing [3].<8:15> PIN assigned by the operating system to identify the process in the processor Condition Code Settings < (CCL) indicates that the DCT in the given system cannot be accessed.
GETREMOTECRTPID Procedure (Superseded by PROCESS_GETPAIRINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The GETREMOTECRTPID procedure is used to obtain the four-word process ID associated with a remote process.
If sysnum specifies a remote system, the process ID is in network form; if sysnum specifies the local system, it is in local form. The two forms differ only in the form of the process name. A local process name consists of six bytes with the first byte being a "$" and the second containing an alphabetic character. The remaining four characters (optional) can be alphanumeric. Note that a full six character local process name cannot be converted to a remote form.
GETSYNCINFO Procedure (Superseded by FILE_GETSYNCINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary The GETSYNCINFO procedure is called by the primary process of a process pair before starting a series of write operations to a file open with paired access. GETSYNCINFO returns a file's synchronization block so that it can be sent to the backup process in a checkpoint message.
• For the Transaction Management Facility, the transaction pseudofile size = 9 words. • For processes, size = 2 words. • For other files, size = 1 word. sync-block-size output INT:ref:1 returns the size, in words, of the sync block data. Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that GETSYNCINFO was successful. > (CCG) indicates that the file is not a disk file.
GETSYSTEMNAME Procedure (Superseded by NODENUMBER_TO_NODENAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The GETSYSTEMNAME procedure supplies the system name associated with a system number.
In either case, the system name is returned in sysname. 0 The specified system does not exist. -1 All paths to the specified system are down. -3 Bounds error occurred on sysname. Considerations When retrieving a line handler logical device number that exceeds 15 bits of magnitude: GETSYSTEMNAME uses the number 32767 to represent any logical device number whose value exceeds 15 bits of magnitude. (The value 32767 is reserved and is never used as an actual logical device number.
GETSYSTEMSERIALNUMBER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The GETSYSTEMSERIALNUMBER procedure returns the system serial number of the caller's system as an ASCII character string of numerals.
Example The following example calls GETSYSTEMSERIALNUMBER and displays the result: main() { #define MAX_ID_LEN 60 char idbuf[MAX_ID_LEN]; short error; short idlen; if (error = GETSYSTEMSERIALNUMBER(idbuf, MAX_ID_LEN, &idlen)) printf("GETSYSTEMSERIALNUMBER error %d\n", error); else { idbuf[idlen] = '\0'; printf("System serial number is %s\n", idbuf); } } GETSYSTEMSERIALNUMBER Procedure 675
GIVE^BREAK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The GIVE^BREAK procedure returns BREAK to the previous owner (the process that owned BREAK before the last call to TAKE^BREAK). GIVE^BREAK is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
Related Programming Manual For programming information about the GIVE^BREAK procedure, see the Guardian Programmer's Guide.
GROUP_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The GROUP_GETINFO_ procedure returns attributes of the specified group, such as the group's textual description and whether the group is automatically deleted when the last member is deleted. The group can be identified by group name or group ID.
group-curlen input, output INT .EXT:ref:1 on input, if group-name is specified, contains the actual length (in bytes) of group-name. The default value is 0. On output, if group-name is returned, this parameter contains the actual length (in bytes) of group-name. This parameter is required if group-name:group-maxlen is specified. groupid input, output INT(32) .EXT:ref:1 on input, if group-curlen is 0 or omitted, specifies the group ID for which information is to be returned.
22 Parameter out of bounds. An input parameter is not within the valid range, or return information does not fit into the length of the space provided, or an output parameter overlays the stack marker that was created by calling this procedure. 29 Missing parameter. This procedure was called without specifying a required parameter. 590 Bad parameter value.
GROUP_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The GROUP_GETNEXT_ procedure returns a group name and group ID. On successive calls, all group names and group IDs can be obtained.
groupid output INT(32) .EXT:ref:1 returns the group ID corresponding to the returned group-name. groupid is a value in the range 0 through 65535. Returned Value INT A file-system error code that indicates the outcome of the call. Common errors returned are: 0 No error. 11 Record not in file. There are no more groups, or the specified group name is undefined. 22 Parameter out of bounds.
GROUPIDTOGROUPNAME Procedure (Superseded by GROUP_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support file-sharing groups. The GROUPIDTOGROUPNAME procedure returns the group name associated with an existing group ID from the USERID file.
Example INT .NAME^ID [ 0:3 ] := 8; !this is ACCTING group! . . .
GROUPMEMBER_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The GROUPMEMBER_GETNEXT_ procedure returns a user member or alias associated with a group ID. On successive calls, all user members and aliases associated with a given group ID can be obtained.
member-name is passed, and returned, in one of two forms: group name.user member The group name and user member are each up to 8 alphanumeric characters long, and the first character must be a letter. The group name and user member are separated by a period (.). alias The alias is a case-sensitive string made up of 1 to 32 alphanumeric characters, periods (.), hyphens (-), or underscores (_). The first character must be alphanumeric. member-curlen input, output INT .
GROUPNAMETOGROUPID Procedure (Superseded by GROUP_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support file-sharing groups. The GROUPNAMETOGROUPID procedure returns the group ID associated with an existing group name from the USERID file.
Example INT .NAMEID [0:3] := ["GATORS "]; !want to get group ID . . CALL GROUPNAMETOGROUPID (NAMEID); !on return, NAMEID[0].<8:15> = contains the group ID IF <> THEN ...
7 Guardian Procedure Calls (H-K) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letters H through K. Table 24 lists all the procedures in this section.
HALTPOLL Procedurè Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Example Related Programming Manuals Summary The HALTPOLL procedure is normally used to stop continuous polling. Syntax for C Programmers #include _cc_status HALTPOLL ( short filenum ); • The function value returned by HALTPOLL, which indicates the condition code, can be interpreted by _status_lt(), _status_eq(), or _status_gt() (defined in the file tal.h).
HEADROOM_ENSURE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary NOTE: This procedure can be called only from a native process. Its pTAL syntax is declared only in the EXTDECS0 file. The HEADROOM_ENSURE_ procedure allows you to check that the current stack has enough room for the needs of your process.
Returned Value INT(32) If room is <= 0D, ret-val indicates the number of bytes between the current stack pointer and the stack limit. If room is > 0D, ret-val indicates the outcome of the operation and returns one of these values: 0D Either the requested space already exists in the stack space or the stack space was successfully enlarged to make enough room for the request. 5D The request would have exceeded the maximum stack size. 6D The stack pointer is invalid.
HEAPSORT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The HEAPSORT procedure is used to sort an array of equal-sized elements in place. Syntax for C Programmers #include short HEAPSORT ( short ,short ,short ,short • _near *array num-elements size-of-element (*)()compare-function ); The compare-function parameter is an application-supplied comparison function that must be written in C.
compare-proc input INT PROC is an application-supplied function procedure that HEAPSORT calls to determine the sorted order (ascending or descending) of the elements in array. This procedure must be of the form: INT PROC compare-proc ( element-a, element-b ); INT .element-a; INT .element-b; The compare-proc must compare element-a with element-b and return either of these values: 0 (indicating false) if element-b should precede element-a. 1 (indicating true) if element-a should precede element-b.
HEAPSORTX_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The HEAPSORTX_ procedure is used to sort an array of equal-sized elements in place. Syntax for C Programmers NOTE: In the TNS/E environment, the CEXTDECS file uses the int data type for 32-bit values. This is a change from the TNS and TNS/R environments where CEXTDECS uses the long data type for 32-bit values.
size-of-element input INT:value is the size, in words, of each element in array. compare-proc input INT PROC is an application-supplied function procedure that HEAPSORTX_ calls to compare two array elements and determine their sorted order. The addresses of these elements are supplied as parameters to compare-proc. This procedure must be of the form: INT PROC compare-proc ( element-a , element-b ); INT .EXT element-a; INT .
Example In the following example, HEAPSORTX_ sorts the elements in ARRAY in ascending order: CALL HEAPSORTX_ ( array, num^elements, element^size, ascending ); Related Programming Manual For programming information about the HEAPSORTX_ procedure, see the Guardian Programmer's Guide.
HIST_FORMAT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value workspace.FormatSelect Field Protected Context Considerations Examples Summary The HIST_FORMAT_ procedure produces an ASCII text representation of the process state whose context is established by a previous call to the HIST_INIT_ procedure or HIST_GETPRIOR_ procedure. The FormatSelect field inside the workspace structure determines what information is reported back by HIST_FORMAT_ to the caller.
limit input INT:value specifies the maximum length (in bytes) of the output line. This value must not be less than the minimum width specified by the HIST_MinWidth literal in the HHISTRY file; otherwise, an error occurs. Returned Value INT If the procedure is successful, the length of the output text in bytes or zero (0) if there is no more text for the current context.
HF_LocLineRISC For procedures executing in TNS/R native mode, shows the program counter (pc), virtual frame pointer (VFP), frame pointer (FP), and stack pointer (sp), when relevant, in hexadecimal. HF_LocLineIPF is the TNS/E equivalent for HF_LocLineRISC. The FP is used to access formal parameters and local variables of the procedure. It is typically the stack pointer (sp). The output identifies the pointer and displays its value for any procedure with a stack frame.
The default FormatSelect value set by the HIST_INIT_ procedure is HF_trace unless the HO_OneLine or HO_Init_address bit is set in the options parameter of the HIST_INIT_ procedure call; in that case, the default value is HF_base + HF_Parent. HF_withContext causes the full context to be displayed whenever a new context is available, such as at the invocation of a signal handler. HF_full causes all available state information to be displayed for native frames.
Returned Text Explanation was generated by tracing the stack to the privileged boundary, before the switch to nonprivileged mode to enter the user's signal handler occurred. AnotherProc + 0x2F8 (UCr) Indicates the call site of USER_PROC. If the signal handler instead passed its uContext and specified the HO_Init_uContext option to HIST_INIT_, the trace would start with PRIV_PROC_ and otherwise appear the same.
An example trace in the TNS/R environment : xtracer + 0x60 (UCr) handler + 0x170 (UCr) ... HIST_TEST_ACTOR_ + 0x2F0 (UCr) PROGRAM + 0x510 (UCr An example trace in the TNS/E environment : options=HO_Init_Here FormatSelect=HF_trace xtracer + 0x110 (UCr) handler + 0x220 (UCr) ... HIST_TEST_ACTOR + 0x80 (UCr) main + 0xAD0 (UCr) _MAIN + 0x160 (UCr) For the next trace: • options equals HO_Init_Here + HO_ShowProtected. • FormatSelect equals HF_trace (the default value).
For the next trace: • options equals HO_Init_Here + HO_ShowProtected. • FormatSelect equals HF_trace (the default value) + HF_Context. The resulting trace shows the full context at the point of the trap and the partial context at the transition to privileged state.
An example trace in the TNS/E environment: options=HO_Init_Here + HO_ShowProtected FormatSelect=HF_trace + HF_Context xtracer + 0x110 (UCr) handler + 0x220 (UCr) --doer + 0x170 (UCr) Mode=Native, Priv pc:0x0000000070001910 rp:0x0000000070001C00 psp:0x000000006DFDFE80 sp:0x000000006DFDFE00 cfm:0x000000000000060E bsp:0x000000006DF04100 lc:0x0000000000000000 ec:0x0000000000000000 pred:0x0000000000001201 Static general registers (0:31) 000: 0000000000000000 00000000080003F0 400000000000058D E00000020150
026: 0000000000000000.0000000000000000 0000000000000000.0000000000000000 028: 0000000000000000.0000000000000000 0000000000000000.0000000000000000 030: 0000000000000000.0000000000000000 0000000000000000.0000000000000000 main + 0xAD0 (UCr) _MAIN + 0x160 (UCr) For the next trace: • options equals HO_Init_Here + HO_ShowProtected. • FormatSelect equals HF_trace (the default value) + HF_LocLineRISC. The resulting trace shows the pc, VFP, FP, and sp registers.
An example trace in the TNS/E environment: options = HO_Init_Here + HO_ShowProtected FormatSelect = HF_trace + HF_LocLineIPF xtracer + 0x110 (UCr) pc:0x0000000070000CD0 psp:0x000000006FFFDFD0 sp:0x000000006FFFCD70 psp:0x000000006FFFE050 sp:0x000000006FFFDFD0 psp:0x000000006DFDFE80 sp:0x000000006DFDFE00 handler + 0x220 (UCr) pc:0x0000000070001520 --doer + 0x170 (UCr) pc:0x0000000070001910 ...
An example trace in the TNS/R environment: xtracer + 0x60 (UCr) handler + 0x170 (UCr) PK_SIG_HANDLER_JACKET_ + 0x68 (SLr) --caller + 0x28 (UCr) HIST_TEST_ACTOR_ + 0x2BC (UCr) PROGRAM + 0x510 (UCr) An example trace in the TNS/E environment: options =HO_Init_Here + HO_ShowProtected + HO_NoSuppress FormatSelect = HF_trace xtracer + 0xF0 (UCr) handler + 0x220 (UCr) $UD_S__SigHandlerJacket + 0x3B0 (SLr) --caller + 0x100 (SLr) HIST_TEST_ACTOR_ + 0xB0 (UCr) main + 0xAD0 (UCr) _MAIN + 0x160 (UCr) Example Traces
An example trace in the TNS/E environment: (millicode example) options=HO_Init_uContext + HO_NoSuppress FormatSelect=HF_trace copyData + 0x6C51 (Milli) _SharedMilli_MOVB_FWD + 0x2B0 (Milli) doer + 0x1A0 (UCr) HIST_TEST_ACTOR + 0xC0 (UCr) main + 0xB10 (UCr) _MAIN + 0x160 (UCr) In the next trace: • options equals HO_Init_uContext + HO_NoSuppress, and the address of the handler's context is passed in the context parameter of HIST_INIT_. • FormatSelect equals HF_trace (the default value) + HF_Context.
An example trace in the TNS/E environment: options=HO_Init_uContext + HO_NoSuppress FormatSelect=HF_trace + HF_Context copyData + 0x6C51 (Milli) Mode=Native pc:0xFFFFFFFFE25145B1 rp:0xFFFFFFFFE250C2F0 psp:0x000000006FFFFC10 sp:0x000000006FFFF560 cfm:0x0000000000002E5C bsp:0x000000006E0002C8 lc:0x0000000000000000 ec:0x0000000000000000 pred:0x0000000000001FC1 Static general registers (0:31) 000: 0000000000000000 FFFFFFFFE2804BE0 4000000000000008 E000000201508070 004: 0000000000000000 0000000000000000 00000
In the next trace: • options equals HO_Init_uContext + HO_NoSuppress, and the address of the handler's context is passed in the context parameter of HIST_INIT_. • FormatSelect equals HF_trace (the default value) + HF_LocLineRISC (in the TNS/R environment) or HF_LocLineIPF (in the TNS/E environment).
For the next trace: • options equals HO_Init_Here. • FormatSelect equals HF_trace (the default value) + HF_LocLineTNS. SHTC.xtracer + %37 (UC.00) P=%001314 E=%000200:T,UC.00 L=%023502 S=%024142 main + %740 (UC.00) P=%001071 E=%000200:T,UC.00 L=%023453 _MAIN + %32 (UC.00) P=%000125 E=%000200:T,UC.00 L=%023430 The next trace is from an accelerated version of the same program: • options equals HO_Init_Here. • FormatSelect equals HF_trace (the default value) + HF_LocLineTNS.
For the next trace: • options equals HO_Init_Here. • FormatSelect equals HF_trace + HF_NameFull. XTRACER + 0x140 (UCr) .CHILD_PROCEDURE_SUBPROC_ATTRIBUTE_ACTIVE_CALL_FORMAT_FRAMEGENERATOR_CONT>> AINERID_10XPACKAGE_HASH_VX_75_LIMIT_C + 0x40 (UCr) PARENT_PROCEDURE_CALL_STD131CHARACTER_RULE_TARGET_UNIQUEID_BASIC_STRING_A>> LLOCATOR__TM_65_72_C + 0x20 (UCr) MAIN_PROCEDURE + 0x20 (UCr) For the next trace: • options equals HO_Init_Here. • FormatSelect equals HF_Parent + HF_trace (the default value).
HIST_GETPRIOR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary The HIST_GETPRIOR_ procedure establishes a previous procedure call as the process context for display by the next HIST_FORMAT_ procedure call. For an overview of how HIST_INIT_, HIST_FORMAT_, and HIST_GETPRIOR_ can be used together to perform stack tracing, see the HIST_INIT_ Procedure (page 716).
-8 HIST_ERROR The stack tracing mechanism failed. -9 HIST_BAD_WORKSPACE The workspace structure has an invalid version identifier. This error can occur if HIST_GETPRIOR_ is called without first calling the HIST_INIT_ procedure or if the workspace structure has become corrupted. Considerations • Suppression of a stack frame by HIST_INIT_ or HIST_PRIOR_ is determined by a bit mask in the field workspace.FrameSuppress.
HIST_INIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The HIST_INIT_ procedure initializes a process history display or stack trace. It validates parameter and establishes the context to display and from which to begin tracing. HIST_INIT_ is used with the HIST_FORMAT_ and HIST_GETPRIOR_ procedures to provide the ability to display process state, including register contents and procedure activation history or stack traces.
The address of this workspace area is passed to subsequent calls to the HIST_FORMAT_ and HIST_GETPRIOR_ procedures. version input INT(32):value HistVersion1 is a literal value defined in HHISTRY to identify the initial 32-bit version of the workspace. HistVersion3 is a literal value defined in HHISTRY to identify the 64-bit version of the workspace. 32-bit processes might specify either version. 64-bit processes must specify HistVersion3.
In addition, the displayed context is affected when any combination of these bits are set to 1: <11> HO_NoSuppress enables the display of transition frames, including the shells by which TNS code calls native procedures, the system procedure that calls a signal handler, and some transitions within low-level system software. By default, transition frames are not displayed. <10> HO_ShowProtected enables the display of protected context when a signal is generated within protected code.
The stack tracing mechanism failed while attempting to trace back to the calling procedure. -11 HIST_MISSING_HOOK This error is not returned in the D40 RVU. -12 HIST_TOO_SHORT A workspace length is less than the size of the NSK_histWorkspace structure. -13 HIST_BAD_PIN An invalid argument (pin) is passed. -14 HIST_BAD_HOOK Unable to read the unwind information associated with the specified function. -15 HIST_BAD_SESSION An invalid session handle is passed.
context to be displayed. A double loop of HIST_FORMAT_ and HIST_GETPRIOR_ procedure calls then displays a history of context transitions: HIST_FORMAT_ provides the text for display, and HIST_PRIOR_ establishes the next context (for the previous procedure). The HO_Init_Address option of HIST_INIT_ does not start a stack trace. It generates only one context. However, the same loop of calls still works; the loop simply terminates after one iteration. When this option is specified, the only effective workspace.
INCREMENTEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Example Related Programming Manual Summary The INCREMENTEDIT procedure sets the increment to be added to successive line numbers for lines that will be added to an EDIT file without explicitly specified line numbers. Each time a file is opened by OPENEDIT or OPENEDIT_, the increment is reset to 1 (which would be specified in this procedure as 1000).
Example In the following example, INCREMENTEDIT sets the line number increment value to 10. INT(32) increment := 10000D; . . CALL INCREMENTEDIT ( filenumber, increment ); Related Programming Manual For programming information about the INCREMENTEDIT procedure, see the Guardian Programmer's Guide.
INITIALIZEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Nowait Considerations Example Related Programming Manual Summary The INITIALIZEEDIT procedure allocates the EDIT file segment (EFS) to be used by IOEdit and initializes the data structures that it contains. If your program uses IOEdit, this procedure is called automatically by the first IOEdit procedure that your program calls.
maxfiles input INT:value specifies the maximum number of files that IOEdit will be able to have open at one time. If this parameter is omitted or if a value less than 30 is specified, 30 is used. If a value greater than 255 is specified, 255 is used. errorabend input INT:value specifies the action that INITIALIZEEDIT is to take if it is unable to allocate the EFS on any disk volume.
• If nowait-option is set to 2 or 3 and IOEdit determines that the file is being accessed sequentially, IOEdit reads ahead and writes behind for all files, not just those opened for nowait access. • If nowait-option is set to 1, 2, or 3 and the calling process calls AWAITIO[X] with the file number set to -1 (any file), you must call COMPLETEIOEDIT to let IOEdit know when the nowait operation on the buffer has finished, even if the process is accessing nonedit files nowait.
INITIALIZER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The INITIALIZER procedure is used to read the startup message and, optionally, to request receipt of assign and param messages sent by the starting process (which is often a TACL process). The INITIALIZER procedure optionally initializes file control blocks (FCBs) with the information read from the startup and assign messages.
These procedures must be of the form: PROC name ( [ ,[ ,[ ,[ ,[ rucb ] passthru ] message ] msglen ] match ] ) VARIABLE; rucb INT:ref:* is the run-unit control block described in the Guardian Programmer's Guide. passthru INT:ref:* is an array where the procedure can save information for or retrieve information from the caller of INITIALIZER. message INT:ref:* is the startup message, the param message, or one of the assign messages received.
timelimit input INT(32):value specifies how long INITIALIZER is to wait on $RECEIVE, as follows: >= 0D timelimit specifies the maximum amount of time (in units of 0.01 second) that INITIALIZER is to wait on $RECEIVE. = -1 DINITIALIZER is to wait indefinitely. < -1 DINITIALIZER calls ABEND. If this parameter is omitted, the default value 6000D (60 seconds) is used. num^fcbs input INT:value specifies the number of FCBs passed in the fcb^array parameter.
FCBs by using the CHECK^FILE procedure. For additional about SIO procedures, see the Guardian Programmer's Guide. • Assign and param messages Except when invoked by the backup process of a process pair, INITIALIZER reads the startup message, then optionally requests assign and param messages (see flags.<11>. For each assign message, the FCBs (if rucb is passed) are searched for a logical file name matching the logical file name contained in the assign message.
INTERPRETINTERVAL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The INTERPRETINTERVAL procedure takes a fixed variable (quad) containing a value representing a number of microseconds and converts it into a combination of days, hours, minutes, seconds, milliseconds, and microseconds. All output parameters are optional.
minutes output INT:ref:1 returns the number of minutes in the interval of time (0 or greater). seconds output INT:ref:1 returns the number of seconds in the interval of time (0 or greater). milsecs output INT:ref:1 returns the number of milliseconds in the interval of time (0 or greater). microsecs output INT:ref:1 returns the number of microseconds in the interval of time (0 or greater).
INTERPRETJULIANDAYNO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Related Programming Manual Summary The INTERPRETJULIANDAYNO procedure converts a Julian day number to the year, month, and day. The Julian calendar is the integral number of days since January 1, 4713 B.C. The formal definition of the Julian day states that it starts at 12:00 (noon), Greenwich mean time (GMT).
day output INT:ref:1 returns the Gregorian day of the month (1-31). Example CALL INTERPRETJULIANDAYNO ( JULIANDAYNO, YR, MN, DAY ); Related Programming Manual For programming information about the INTERPRETJULIANDAYNO procedure, see the Guardian Programmer's Guide.
INTERPRETTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The INTERPRETTIMESTAMP procedure converts a 64-bit Julian timestamp into a Gregorian (the common civil calendar) date and time of day.
[6] The millisecond of the second (0-999) [7] The microsecond of the millisecond (0-999) Returned Value INT(32) The 32-bit Julian day number. A value of -1D is returned if the supplied Julian timestamp is out of range (see Considerations). Considerations • INTERPRETTIMESTAMP checks that the Julian timestamp corresponds to a time in the range 1 January 0001 00:00 through 31 December 10000 23:59:59.999999.
IPUAFFINITY_CONTROL_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The IPUAFFINITY_CONTROL_ procedure controls scheduling features which are not associated with a single process. It can also clear all the settings as well as all the process-to-IPU associations, thus bringing the system or CPU back to its initial state with respect to process scheduling.
Parameters TargetCPU input INT:value specifies the CPU to which the action is directed. A value of -1 means all the CPUs in the local system. When -1 is specified, the first CPU which encounters an error (other than a down CPU error) results in that error being returned without attempting the setting on the other CPUs. It is expected that if an error is returned for any CPU then it would be returned for all CPUs, given the possible errors.
Returned Value INT A file system error code that indicates the outcome of the call: 0 FEOK The procedure executed successfully. 22 FEBOUNDSERR An invalid address was specified for the previousControlFlags parameter. 48 FESECVIOL The caller does not have the necessary permissions. See Considerations below for details. 564 FEBADOP Invalid controlFlagsMask bits were set. 590 FEBADPARMVALUE An invalid or down CPU was specified.
Example The following C example turns off DP2 balancing in the process scheduler in CPU 3: int16 tgt_phandle[10]={0}; uint16 tgt_cpu=3; uint64 controlFlagsMask=(1 << 62); uint64 controlFlagsSetting=0; uint64 prevcontrolFlags; err=IPUAFFINITY_CONTROL_(tgt_cpu, controlFlagsMask, controlFlagsSetting, &prevcontrolFlags); if (err) printf("Error %d from IPUAFFINITY_CONTROL_\n", err); else printf("DP2 Balancing was turned off in CPU %d\n", tgt_cpu); IPUAFFINITY_CONTROL_ Procedure 739
IPUAFFINITY_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The IPUAFFINITY_GET_ procedure returns the current IPU number associated with a process, which is the IPU number set via IPUAFFINITY_SET_, if that is in effect, or the current assignment by the process scheduler otherwise. In the latter case, the IPU number may change in parallel with this procedure call.
TargetIPU output INT .EXT:ref:1 on successful return, contains the IPU number associated with the target process. Options output INT(32) .EXT:ref:1 on successful return, contains the IPU affinity options associated with this process. This is a bit mask (with bit 0 being the high-order bit, and bit 31 being the low-order bit) defined as follows: <31> <30> 0 The process is not currently bound to an IPU via IPUAFFINITY_SET_. 1 The process is currently bound to the TargetIPU.
printf("Error %d from IPUAFFINITY_GET_\n", err); else { if(aff_options & 1) printf("$XYZ is bound to IPU %d\n", tgt_ipu); else printf("$XYZ is currently on IPU %d, but is not bound.
IPUAFFINITY_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Summary The IPUAFFINITY_SET_ procedure associates a process with a given IPU within its CPU. The process scheduler does not move this process after the association has been set (without another call to this procedure). IPUAFFINITY_SET_ can also be used to remove such an association.
Parameters Process Handle input INT .EXT:ref:10 points to the process handle of the target process. Error 14 is returned if the specified process has stopped, is in an invalid or down CPU, or is otherwise non-existent or invalid. Target IPU input INT:value specifies the IPU number to associate with the target process. This parameter is ignored if Options bit 31 is 0. Options input INT(32):value specifies IPU affinity options.
Considerations CAUTION: Setting a process on an IPU restricts the ability of the process scheduler to dynamically balance the workload of the CPU or improve its responsiveness. Performance problems can arise for the associated processes if the performance and workload characteristics are not well understood in the context of the overall customer workload. See the Guardian Programmer's Guide for additional guidelines on the usage of this interface.
else printf("The IPU affinity of $XYZ process has been unbound\n"); } 746 Guardian Procedure Calls (H-K)
JULIANTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The JULIANTIMESTAMP procedure returns either a four-word, microsecond-resolution, Julian-date-based timestamp or the number of microseconds elapsed since the last system load. The Julian calendar is the integral number of days since January 1, 4713 B.C.
tuid output INT:ref:1 is a time-update ID. This is used when calling the SYSTEMCLOCK_SET_ or SETSYSTEMCLOCK procedure with relative GMT. See the SYSTEMCLOCK_SET_ Procedure (page 1408). error output INT:ref:1 is returned only from a remote system with one exception: a value of -1 is returned when type is out of range. node input INT:value is the system number of the remote node from which you want the timestamp. A value of -1 indicates that this parameter is not present and that the current node is used.
December 1974. Note that this is not a Julian timestamp and therefore it is not transferable across HP systems. Applications should avoid using the RCLK instruction except where necessary. • Process timing uses 64-bit elapsed time counters with microsecond resolution; these are also not Julian timestamps. • There is no way to generalize about internal timing using 64-bit Julian timestamps or 48-bit timestamps.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manual Summary NOTE: These procedures are supported for compatibility with previous software and should not be used for new development. The KEYPOSITION[X] procedures are used to position by primary or alternate key within a structured file.
Syntax for TAL Programmers CALL KEYPOSITION[X] ( filenum ,key-value ,[ key-specifier ] ,[ length-word ] ,[ positioning-mode ] ); ! ! ! ! ! i i i i i Parameters filenum input INT:value is the number of an open file where the positioning is to take place. key-value input STRING:ref:* (for KEYPOSITION) STRING .EXT:ref:* (for KEYPOSITIONX) is the address of the buffer in the stack containing the key value (KEYPOSITION) or the address of the buffer containing the key value (KEYPOSITIONX).
of the primary key. If key-specifier is the key-specifier for an alternate key, the length of the alternate-key field is used. • If length-word is 0, compare-length and key-length are also 0. This results in positioning to the beginning of the file. (Although key-value is still a required parameter, its value is ignored when length-word = 0.) • If key-length = 0 and compare-length <> 0, file-system error 21 is returned from KEYPOSITION.
Considerations • The calling application process is not suspended because of a call to KEYPOSITION. • The KEYPOSITION and KEYPOSITIONX procedures expect primary-key values for relative and entry-sequenced files to be in four-byte form. Thus, these procedures cannot be used with format 2 files (which require keys in eight-byte form). If an attempt is made to use these procedures with format 2 files, error 581 is returned.
• Saving current position When positioning by standard (not insertion-ordered) alternate key, you can save the current file position for later access by concatenating alternate-key value and primary key values in a temporary buffer. This permits you to return to that position in a key-sequenced file; for example: temporary-buffer ':=' record.altkeyfield FOR $LEN (record.altkeyfield) & record.primarykey FOR $LEN (record.
A similar situation arises when you read a key-sequenced file with duplicate alternate keys. When an alternate-key file allows duplicate alternate keys that are ordered by primary-key value (the standard ordering method), key-value must be thought of as having two parts: the alternate-key value and the primary-key value. You can specify both parts or you can specify the alternate-key value only.
• KEYPOSITION and file-system error 21 If any of these conditions are true, error 21 is returned by KEYPOSITION: ◦ ◦ • If the primary file is a key-sequenced file and one of these is true: – key-specifier is omitted or 0 and key-length is greater than the key length defined for the primary file. – compare-length is greater than key-length.
Related Programming Manual For programming information about the KEYPOSITION procedure, see the Enscribe Programmer's Guide and the Guardian Programmer's Guide.
8 Guardian Procedure Calls (L) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter L. Table 25 lists all the procedures in this section.
LABELEDTAPESUPPORT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Related Programming Manual Summary The LABELEDTAPESUPPORT procedure is callable; it provides a way for nonprivileged programs to determine if tape label processing is enabled in the system.
LASTADDR Procedure (Superseded by ADDRESS_DELIMIT[64]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The LASTADDR procedure returns the ‘G'[0] relative address of the last word in the application process' data area. (To obtain the last extended address available, use LASTADDRX.
LASTADDRX Procedure (Superseded by ADDRESS_DELIMIT[64]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Example Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The LASTADDRX procedure allows user programs to check stack limits or parameter addresses. LASTADDRX returns the last extended address available in the specified relative segment.
NOTE: There are additional considerations for privileged callers. Returned Value INT(32) The last valid extended address in the segment indicated by seg. If either the segment is not allocated, the segment is a flat segment, or there is a parameter error, a value of -1D is returned. Example LITERAL FEBOUNDSERR=22; IF ADDR > LASTADDRX ( $HIGH(ADDR).
LASTRECEIVE Procedure (Superseded by FILE_GETRECEIVEINFO[L]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The LASTRECEIVE procedure is used to obtain the four-word process ID and the message tag associated with the last message read from the $RECEIVE file.
If the process ID is of the unnamed form and thus not in the DCT, the information returned consists of: [0:2] [3] creation-time-stamp .<0:3> Reserved .<4:7> Processor number where the process is executing .<8:15> PIN assigned by operating system to identify the process in the processor If the process ID is of the network form, the information returned consists of: [0] .<0:7> "\" [0] .<8:15> System number [1:2] [3] Process name .<0:3> Reserved .
for distinguishing, for example, one requester from another requester. For further details, see the Guardian Programmer's Guide. • Remote opener with a long process file name If the calling process used FILE_OPEN_ to open $RECEIVE and did not request to receive C-series format messages, and if the last message read from $RECEIVE is from a remote process that has a process name consisting of more that five characters, then the value of process-id returned by LASTRECEIVE is undefined.
LOCATESYSTEM Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The LOCATESYSTEM procedure provides the system number corresponding to a system name and returns the logical device number of the line handler controlling the path to a given system.
The line handler exists and the specified system is accessible, but the line handler logical device number exceeds 15 bits of magnitude. or The specified system is the local system, so there is no line handler logical device number to return. In either case, the system number is returned in sysnum. 0 The specified system does not exist. -1 All paths to the specified system are down. -3 Bounds error occurred on sysname or sysnum.
LOCKFILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Related Programming Manual Summary The LOCKFILE procedure is used to exclude other users from accessing a file (and any records within that file). The "user" is defined either as the opener of the file (identified by filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
Parameters filenum input INT:value is the number of an open file that identifies the file to be locked. tag input INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this LOCKFILE. NOTE: The system stores the tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO, thus indicating that the operation completed.
NOTE: For non-audited files, a deadlock condition—a permanent suspension of your application—occurs if READ or READUPDATE is called by the process which has a record locked by a filenum other than that supplied in READ or READUPDATE. (For an explanation of multiple opens by the same process, see the FILE_OPEN_ Procedure (page 457).
LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for buffer Considerations OSS Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The LOCKINFO provides information about locks (held or pending) on a local DP2 disk volume.
searchid input INT .EXT:ref:12 identifies the volume, file, volume and process, or volume and transaction for which information is to be returned. Words [0:3] of searchid must always contain the name of the local DP2 disk volume that is to be searched. For the four different values of searchtype, these formats apply: searchtype [ 0:3 ] [ 4:7 ] [ 8:11 ] 0 volume ignored ignored 1 volume subvolume file ID 2 volume process ID ignored 3 volume TRANSID ignored ctlwds input, output INT .
21 buffersize is less than the minimum. 22 The address of ctlwds or buffer is out of bounds. 41 Checksum error on ctlwds. The ctlwds parameter has been altered between calls to LOCKINFO or was not initialized before the first call. 45 Information for one locked resource was returned, but the supplied buffer was too small to hold all available lock accessors information (the number of holders/waiters that could be returned is always found in LIB.NUMLABS).
The LABINFO structure is defined for TAL as: STRUCT LABINFO ( * ); BEGIN INT MISC, ! ID type, lock and grant state ! (see below) USERID[ 0:3 ], ! Process ID or TRANSID (see below) RESERVED; ! Reserved for future use. END; Definitions for the MISC word of the LABINFO structure (the remaining bits are reserved for future use): DEFINE IDTYPE=MISC.<0> #, ! ! GRANTSTATE=MISC.<1:3> #, ! INTENTFLAG=MISC.<4> #; ! ! ! ! ! If set: USERID is a process ID 0=Waiting; 1=Granted Indicates the lock is an intent.
LOCKREC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Related Programming Manual Summary The LOCKREC procedure excludes other users from accessing a record at the current position. The "user" is defined either as the opener of the file (identified by filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited. NOTE: LOCKREC operations cannot be used with queue files.
• CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int. • The function value returned by LOCKREC, which indicates the condition code, can be interpreted by _status_lt(), _status_eq(), or _status_gt() (defined in the file tal.h).
locked). The alternate locking mode is specified by calling the SETMODE procedure and specifying function 4. • Attempting to read a locked record in default locking mode If the default locking mode is in effect when READ or READUPDATE is called for a record that is locked by another user, the caller to READ or READUPDATE is suspended and queued in the "locking" queue behind other users attempting to lock or read the record.
mode, the call either fails with file-system error 73 ("record is locked") or is placed in the locking queue. ◦ Record pointers after LOCKREC After a call to LOCKREC, the current-record, next-record, and end-of-file pointers remain unchanged. • Avoiding or resolving deadlocks One way to avoid deadlock is to use one of the alternate locking modes that can be established by SETMODE function 4. A common method of avoiding deadlock situations is to lock records in some predetermined order.
LONGJMP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The LONGJMP_ procedure performs a nonlocal goto. It restores the state of the calling process with context saved in a jump buffer by the SETJMP_ procedure. Control returns to the location of the corresponding SETJMP_ procedure call. Syntax for C Programmers #include
• LONGJMP_ does not return. Normally, return is made at the location of the corresponding SETJMP_ procedure. • The jump buffer is assumed to be valid and initialized by an earlier call to SETJMP_. If an invalid address is passed or if the caller modifies the jump buffer, the result is undefined and could cause the system to deliver a non-deferrable signal to the process. • If LONGJMP_ detects an error, a SIGABRT or SIGILL signal is raised (except for TNS processes).
LOOKUPPROCESSNAME Procedure (Superseded by PROCESS_GETPAIRINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The LOOKUPPROCESSNAME procedure is used to obtain a description of a named process pair by its name or by its index into the local destination control table (DCT).
If the process name is not in the DCT, ppd is unchanged. Condition Code Settings < (CCL) indicates that the specified process name is not in the directory, or that the remote system could not be accessed, or that the specified process pair has a high-PIN process as the primary or backup. = (CCE) indicates that the specified name was found. > (CCG) indicates that the specified entry number exceeds the last table entry.
9 Guardian Procedure Calls (M) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter M. Table 26 lists all the procedures in this section.
MBCS_ANY_KATAKANA_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_ANY_KATAKANA_ procedure checks a string of HP Kanji characters for any Katakana characters. Katakana one-byte characters are permitted in a string of HP Kanji characters.
Returned Value INT Result of the MBCS_ANY_KATAKANA_ test: 0 The buffer string does not contain any Katakana characters or that charset did not specify the HP Kanji multibyte character set. 1 The HP Kanji buffer string contains at least one Katakana character. Considerations The Japanese one-byte Kanji character set is defined in the Japanese Industrial Standard (JIS) X0208 (formerly C6226); the Japanese Katakana character set is defined in JIS X0201 (formerly C6220).
MBCS_CHAR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The MBCS_CHAR_ procedure indicates whether a string of bytes is part of an HP multibyte character set (MBCS) and that testmbcschar points to the first byte of a valid character of charset MBCS. The MBCS_CHAR_ procedure also performs a positive range test on all bytes of the referenced character.
10 HP Chinese Big 5 11 HP Chinese PC 12 HP KSC5601 charinfo input, output INT .EXT:1 on input, charinfo specifies the number of bytes, beginning with testmbcschar, that may be read by the MBCS_CHAR_ procedure. If charinfo is equal to or greater than the size of a single multibyte character of the MBCS identified by charset, the MBCS_CHAR_ procedure tests for the presence of a multibyte character.
Katakana characters also appear within HP Kanji MBCS characters. Furthermore, all byte values which appear as the first byte of HP Kanji characters might also appear in the second byte of HP Kanji characters. Similar ambiguous usage of individual byte values occurs in other supported MBCSs. Proper character identification depends both on value range testing and context.
MBCS_CHARSIZE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Related Programming Manual Summary The MBCS_CHARSIZE_ procedure returns the display size (in columns) and the storage size (in bytes) of multibyte character set (MBCS) characters from the character set specified by the charset parameter.
<0:7> contains the display size (in columns) of the multibyte character identified by the test. <8:15> contains the internal size (in bytes) of the multibyte character identified by the test. Related Programming Manual For programming information about the MBCS_CHARSIZE_ procedure, see the Guardian Programmer's Guide.
MBCS_CHARSTRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_CHARSTRING_ procedure tests the contents of a data string for the exclusive use of MBCS characters of known internal character sets. This procedure depends upon the MBCS_CHAR_ procedure to test each group of bytes in the data string for validity; it inherently supports all the character sets known to the MBCS_CHAR_ procedure.
index output INT .EXT:ref:1 is the byte index of the first byte group found in the string that is not a valid MBCS character and is not a group of blanks (%H20) the size of an MBCS character. charset input INT:value identifies the MBCS to be used. If charset is omitted or null, the default character set from the MBCS_DEFAULTCHARSET_ procedure is used. The MBCS_CHARSTRING_ procedure does not examine or validate the character set identification, but simply passes it on to the MBCS_CHAR_ procedure.
MBCS_CODESETS_SUPPORTED_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Related Programming Manual Summary The MBCS_CODESETS_SUPPORTED_ procedure returns a 32-bit integer value. Each bit of the returned value indicates the presence of a particular multibyte character set (MBCS).
Related Programming Manual For programming information about the MBCS_CODESETS_SUPPORTED_ procedure, see the Guardian Programmer's Guide.
MBCS_DEFAULTCHARSET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Related Programming Manual Summary The MBCS_DEFAULTCHARSET_ procedure returns the default multibyte character set (MBCS) identification. HP systems support various MBCSs in different ways. HP Kanji (Shift-JIS), Chinese Big 5, Chinese PC, Hangul, and KSC5601 data formats are supported as internal code representations.
Related Programming Manual For programming information about the MBCS_DEFAULTCHARSET_ procedure, see the Guardian Programmer's Guide.
MBCS_EXTERNAL_TO_TANDEM_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_EXTERNAL_TO_TANDEM_procedure translates a text string from a specified external format to the HP internal text format.
destination-string input, output INT(32) .EXT:ref:1 is a pointer to a double-word integer containing the extended address of the location to receive the translated text string. After translation, the address points to the byte following the last byte in the destination string. source-length input INT:value is the length, in bytes, of the source text string. maximum-length input, output INT .EXT:ref:1 on input, is the maximum allowable number of bytes of space in the output destination string.
external-form input INT:value indicates the format of the source text stream: • IBM external formats ◦ Data stream without substring frames 0 IBM Kanji only (without subfield strings) ◦ Data stream using SO/SI substring frames 1 IBM Kanji EBCDIC 2 IBM Kanji/Katakana-EBCDIC ◦ Data stream using character attribute substring framing (IBM 3270 data stream only) 11 IBM Kanji EBCDIC 12 IBM Kanji/Katakana-EBCDIC • JEF external formats 3 JEF (Fujitsu) Kanji only 4 JEF (Fujitsu) Kanji EBCDIC 5 JEF (Fujitsu)
When the control string values are not user-supplied, the default values used for control strings expressed in the original null-delimited format are as follows: IBM Kanji [%H0E,null] JEF (Fujitsu) Kanjis [%H88,null] JIS X0208 Kanji [%H1B, %H24,%H42,null] When the control string values are not user-supplied, the default values used for control strings expressed in the alternative format are as follows: IBM Kanji character attribute [null, %H03, %H88, %HA2, %H38] shift-to-one-byte input STRING .
Returned Value INT Procedure error code: 0 Successful completion of the translation. -1 Translation truncated due to lack of destination buffer space. -2 Unknown translation requested. -3 Invalid source string length. -4 Invalid character in Kanji-only source string. -5 Control string parameter too long. 29 Required parameter missing. Considerations • All parameters except shift-to-MBCS and shift-to-one-byte are necessary for a string translation operation.
MBCS_FORMAT_CRT_FIELD_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_FORMAT_CRT_FIELD_ procedure formats Kanji only or mixed data types for specific terminal types.
destination-string input, output INT(32) .EXT:ref:1 is the address of an extended address pointer to the location to receive the formatted text string. Upon return from the format function, this pointer points to the first unfilled byte in the destination string. source-length input INT:value is the length, in bytes, of the source text string. maximum-length input INT: value is the maximum allowable number of bytes of space usable in the output destination string.
screen-start-col input, output INT .EXT:ref:1 on input, contains the starting column on the current line of the screen where the first displayable data character may appear. On output, contains an integer which represents the sum of the screen-start-col and the displayable length of the data inserted into the field by the translate function. shift-to-MBCS input STRING .
MBCS_FORMAT_ITI_BUFFER_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_FORMAT_ITI_BUFFER_ procedure formats ITI buffers for specific terminal types. This procedure is designed to support a known subset of double-byte character set SNA3270 display devices. Formatting is confined to the data area of the ITI buffer.
Parameters source-string input, output INT(32) .EXT:ref:1 is the address of an extended pointer to the source text string to be formatted. Upon return from the format function, this pointer is advanced to point to the byte following the last byte in the source string that was successfully processed by the format ITI buffer operation. destination-string input, output INT(32) .EXT:ref:1 is the address an extended pointer to the location to receive the formatted text string.
maximum-col-count input INT:value indicates the width (in columns) of the display device. finished-length output INT .EXT:ref:1 contains the byte count of the part of the destination string containing successfully translated data. screen-col-count output INT .EXT:ref:1 contains the displayable column count of the formatted buffer. shift-to-MBCS input STRING .
Returned Value INT Procedure error code: 0 Successful completion of the translation. -1 Source string translation incomplete, ran out of destination buffer area. -2 Unknown terminal type specified. -3 Invalid source string length. -4 Invalid character in Kanji only source string. -5 Control string parameter too long. -29 Required parameter missing. Considerations Determining the size of the destination buffer is the responsibility of the calling procedure.
MBCS_MB_TO_SB_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MBCS_MB_TO_SB_ procedure and the companion MBCS_SB_TO_MB_ procedure allow conversion of the ninety-four displayable characters of the ASCII character set between one-byte ASCII and characters of the specified MBCS. The MBCS_MB_TO_SB_ procedure converts multibyte characters to the corresponding one-byte ASCII characters.
charset input INT:value is the optional identifier of the reference MBCS. When omitted or null, the default MBCS character set identifier from the MBCS_DEFAULTCHARSET_ procedure is used. These multibyte character sets are supported by this procedure: 1 HP Kanji 9 HP Hangul 10 HP Chinese Big 5 11 HP Chinese PC 12 HP KSC5601 charinfo output INT .EXT:ref:1 is an optional parameter that returns an indication of any cause of failure.
MBCS_REPLACEBLANK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The MBCS_REPLACEBLANK_ procedure replaces nonstandard blanks. Within multibyte character sets, there are usually characters defined that have a blank display attribute of the same width as the other multibyte characters of the same character set.
charset input INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the default MBCS from the MBCS_DEFAULTCHARSET_ procedure is used. MBCS_REPLACEBLANK_ does not examine or validate the character set identification but simply passes it on to the MBCS_CHAR_ procedure. All MBCSs supported by the MBCS_CHAR_ procedure are inherently supported by this procedure. This procedure replaces different multibyte character pairs depending on the charset value.
MBCS_SB_TO_MB_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MBCS_SB_TO_MB_ procedure and the companion MBCS_MB_TO_SB_ procedure are provided to allow conversion of the ninety-four displayable characters of the ASCII character set between one-byte ASCII and characters of the specified MBCS. The MBCS_SB_TO_MB_ procedure converts one-byte ASCII characters to the corresponding multibyte characters.
charset input INT:value is the optional identifier of the reference MBCS. When omitted or null, the default MBCS character set identifier from the MBCS_DEFAULTCHARSET_ procedure is used. These multibyte character sets are supported by this procedure: 1 HP Kanji 9 HP Hangul 10 HP Chinese Big 5 11 HP Chinese PC 12 HP KSC5601 charinfo output INT .EXT:ref:1 is an optional parameter that returns an indication of any cause of failure.
MBCS_SHIFTSTRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The MBCS_SHIFTSTRING_ procedure upshifts or downshifts all alphabetic characters in a multibyte character set (MBCS) string. Both multibyte alphabetic characters of the specified MBCS and one-byte alphabetic characters of the ASCII character set are case shifted by this procedure.
charset input INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the default MBCS from the MBCS_DEFAULTCHARSET_ procedure is used. This procedure does not examine or validate the character set identification but simply passes it on to the MBCS_CHAR_ procedure. All MBCSs supported by the MBCS_CHAR_ procedure are inherently supported by this procedure. charinfo output INT .EXT:ref:1 indicates the cause of failure of the requested test.
MBCS_TANDEM_TO_EXTERNAL_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MBCS_TANDEM_TO_EXTERNAL_ procedure translates a text string from HP internal format to a specified external text format.
source-length input INT:value is the length, in bytes, of the source text string. maximum-length input, output INT .EXT:ref:1 on input, is the maximum allowable number of bytes of space in the output destination string.
12 IBM Kanji/Katakana-EBCDIC • JEF external formats ◦ Data stream using KI/KO substring frames 3 JEF (Fujitsu) Kanji only 4 JEF (Fujitsu) Kanji EBCDIC 5 JEF (Fujitsu) Kanji/Katakana-EBCDIC • Other external formats 8 JIS X0208 Kanji/JIS X0201 (was C6226/C6220) finished-length output INT .EXT:ref:1 contains the byte count of the part of the destination string containing data which was successfully translated.
shift-to-one-byte input STRING .EXT:ref:* is an optional pointer to a string containing the escape or control string used to indicate a shift to a one-byte character set in the source text string. This string must always be in HP internal (not EBCDIC) character format, regardless of the final form of the source string. This procedure does not contain logic for identifying escape or control strings.
translation, specify the source-length, maximum-length, and external-form parameters, and the other formal parameters can be omitted. • In the HP internal character sets, text bytes having the byte value x20 are used to represent blank characters or spaces in both the one-byte and the two-byte character sets. A one-byte blank is represented by a single x20 byte. A two-byte blank is represented by two consecutive x20 bytes.
codes from the HP internal character set are mapped to the target nondisplayable character code. • The most common definition of an invalid character code is a character pair that is expected to be a two-byte code but has an invalid first or second byte. Any character mapped to either a nondisplayable or invalid character target code becomes nonrecoverable for conversion to the original format.
MBCS_TESTBYTE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The MBCS_TESTBYTE_ procedure returns the identification of a specified byte contained within a text string of mixed data.
On output, if result indicates that buffer[testindex] is part of a multibyte character, then testindex contains the byte index of the first byte of the multibyte character containing the tested byte. charset input INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the MBCS returned from the MBCS_DEFAULTCHARSET_ procedure is used. This procedure does not examine or validate the character set identification, but simply passes it on to the MBCS_CHAR_ procedure.
meet this requirement. ( See MBCS_TRIMFRAGMENT_ Procedure (page 826).) Do not assume that an arbitrarily selected extract from a text string meets this requirement. • This procedure does not alter the contents of the text string. • The MBCS_TESTBYTE_ procedure tests isolated bytes in a text string for MBCS characteristics. On each call to this procedure, the buffer text string is analyzed from the beginning up to a point just past buffer[testindex].
MBCS_TRIMFRAGMENT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary The MBCS_TRIMFRAGMENT_ procedure detects and trims trailing multibyte character fragments from text strings. In conversational mode operations, a string read from a terminal might contain a partial multibyte character at the end of the string; the result perhaps of a read operation of an odd length.
charset input INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the MBCS returned from the MBCS_DEFAULTCHARSET_ procedure is used. This procedure does not examine or validate the character set identification, but simply passes it on to the MBCS_CHAR_ procedure. All MBCSs supported by the MBCS_CHAR_ procedure are supported by this procedure. charinfo output INT .EXT:ref:1 indicates the cause of failure of the requested test.
MESSAGESTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Related Programming Manual Summary The MESSAGESTATUS procedure determines if a particular message received through READUPDATE has been canceled.
notified when pending messages are canceled with a system message -38 if SETMODE function 80 has been enabled. See SETMODE Procedure (page 1317). Related Programming Manual For programming information about the MESSAGESTATUS procedure, see the Guardian Programmer's Guide.
MESSAGESYSTEMINFO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The MESSAGESYSTEMINFO procedure measures the current number of messages to or from a process so it can issue a warning when a limit is nearly reached. MESSAGESYSTEMINFO is used with CONTROLMESSAGESYSTEM. You can use MESSAGESYSTEMINFO during checkout of a program that uses CONTROLMESSAGESYSTEM, for example, to verify that initialization was done as expected.
Returned Value INT A file-system error code that indicates the outcome of the call: 0 Successful, no error. 2 Bad itemcode. 21 Bad value. 22 Bounds error. 29 Missing parameter. See the Guardian Procedure Errors and Messages Manual for more information. Considerations MESSAGESYSTEMINFO is inherently tied to the internal workings of the message system, so one or more of its functions might not be supported by future versions of the message system.
MOM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations OSS Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The MOM procedure provides a process with the four-word process ID of its creator.
For a named remote process, process-id is: [0] .<0:7> “\” (ASCII backslash) .<8:15> System number [1:2] [3] $process-name .<0:3> Reserved .<4:7> Processor number where the process is executing .
MONITORCPUS Procedure (Superseded by PROCESS_MONITOR_CPUS_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Messages Example Summary The MONITORCPUS procedure instructs the operating system to notify the application process if a designated processor module either: • Fails (indicated by the absence of an operating system "I'm alive" message) • Returns from a failed to an operable state (that is, reloaded by means of a command interpreter RELOAD command) The calling applic
Messages • processor down System message -2 (processor down) is received if failure occurs with a processor module that is being monitored (for the description and form of system messages, see the Guardian Procedure Errors and Messages Manual). Note that this message expires in three minutes; it must be read before expiration or it will be lost. • processor up System message -3 (processor up) is received if a reload occurs with a processor module that is being monitored.
MONITORNET Procedure (Superseded by PROCESS_MONITOR_NET_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The MONITORNET procedure enables or disables receipt of system messages concerning the status of processors in remote systems.
MONITORNEW Procedure (Superseded by PROCESS_MONITOR_NEW_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The MONITORNEW procedure enables or disables receipt of the SETTIME and Power On messages. Syntax for C Programmers #include void MONITORNEW ( short enable ); Syntax for TAL Programmers CALL MONITORNEW ( enable ); ! i Parameter enable input INT:value contains one of these values: 0 Disable receipt of messages.
MOVEX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The MOVEX procedure moves data between extended data segments without the need for absolute addressing; it serves both privileged and nonprivileged users.
dest-seg-id input INT:value specifies the segment ID of the extended data segment referenced by dest. If the relative segment in dest does not indicate an extended data segment, dest-seg-id is ignored and may be omitted. Otherwise, dest-seg-id is required and must indicate an existing extended data segment. dest input STRING .EXT:ref specifies the relative extended address of the first byte in the destination location.
• • This table indicates restrictions on data movement from the source to the dest based upon the privileged state of the caller: Relative Segment Source Destination 0 current data ok ok 1 system data not allowed not allowed 2 current code not allowed not allowed 3 user code ok not allowed >3 extended data seg ID <= 2047 ok ok >3 extended data seg ID > 2047 privileged only privileged only MOVEX does not alter the status of the current in-use segment.
MYGMOM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The MYGMOM procedure provides a process that is a member of a batch job with the process ID of its job ancestor (GMOM). See the NetBatch User's Guide for information on batch processing.
MYPID Procedure (Superseded by PROCESSHANDLE_GETMINE_ Procedure and PROCESSHANDLE_DECOMPOSE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The MYPID procedure provides a process with its own processor and PIN number. This one-word quantity has been called the PID of a process, with no connection to the four-word process ID.
MYPROCESSTIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Related Programming Manual Summary The MYPROCESSTIME procedure returns the process execution time of the calling process. Process time is the processor time in microseconds that the process has consumed; processor time used for system procedures called is also included.
MYSYSTEMNUMBER Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure or PROCESSHANDLE_GETMINE_ Procedure and PROCESSHANDLE_DECOMPOSE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The MYSYSTEMNUMBER procedure provides a process with its own system number.
MYTERM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The MYTERM procedure provides a process with the file name of its home terminal. The file name returned from MYTERM is suitable for passing directly to any Guardian procedure that accepts a file name in internal form.
10 Guardian Procedure Calls (N) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter N. Table 27 lists all the procedures in this section.
NEWPROCESS[NOWAIT] Procedures (Superseded by PROCESS_LAUNCH_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters NEWPROCESSNOWAIT Completion Message Error Codes and Subcodes General Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations Examples Related Programming Manual Summary NOTE: These procedures are supported for compatibility with previous software and should not be used for new development.
Syntax for C Programmers These procedures do not have a C syntax, because they are superseded and should not be used for new development. These procedures are supported only for compatibility with previous software.
filenames[36:37] = tag is a two-word value used to identify the completion message from the call to NEWPROCESSNOWAIT. This field is unused by NEWPROCESS. See NEWPROCESSNOWAIT Completion Message (page 851). priority input INT:value is a value consisting of three parts: <0> is the debug bit. If priority.<0> = 1, the system sets a code breakpoint on the first executable instruction of the program's MAIN procedure. <1> determines use of the additional fields of the filenames parameter. If priority.
If the process ID is to be passed to any of the appropriate file-system procedures that accept file names, such as OPEN, use a 12-word array. The procedure will fill in only the first 4 words, and the user must blank-fill the other 8. process-id is not used by NEWPROCESSNOWAIT calls. error output INT:ref:1 returns two error code values indicating the outcome of the process creation attempt. The values each occupy one byte in a 16-bit word as follows: error.<0:7> error error.
flags.<14:15> set the debugging attributes for the new process: flags.<14> 1 0 flags.<15> 1 0 Saveabend file creation No saveabend file creation INSPECT DEBUG When flags is specified, bits <14> and <15> are ORed with the corresponding flags in the object code file. If flags.<14> is set but flags.<15> is not, then flags.<15> is also set.
Error Codes and Subcodes Table 28 summarizes the error and error-detail values that can be returned by NEWPROCESS[NOWAIT]. (For information about similar process creation errors (issued by PROCESS_LAUNCH_ and PROCESS_CREATE_), see Table 35 (page 1061) and Table 36 (page 1069).) Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values error Description (including error-detail values, when applicable) 0 No error, process created.
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 29 Library file has too many TNS code segments. 30 Native code length in the program file is invalid. 31 Native code length in the library file is invalid. 32 Native code address in the program file is invalid. 33 Native code address in the library file is invalid. 34 Native data length in the program file is invalid.
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 63 An internal structure of the library file contains an error. 64 An internal structure of the program file has an entry point value of 0. 65 An internal structure of the library file has an entry point value of 0. 66 An internal structure of the program file contains an error. 67 An internal structure of the library file contains an error.
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 97 (TNS/R only) The library file uses a shared run-time library (SRL) and is switching to a new library, but the program was accelerated by an old version of the Accelerator program that does not support SRL data relocation at fixup time. Use a version of the Accelerator program provided with the D30.00 or later RVU of the operating system.
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 13 Extended data segment initialization error: the error-detail is a file-system error number.1 14 Extended segment swap file error: the error-detail is a file-system error number.1 15 Invalid home terminal: the error-detail is a file-system error number.1 16 I/O error to home terminal: the error-detail is a file-system error number.
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 40 (TNS/R only) A shared run-time library (SRL) requires fixups to another SRL that is unavailable because it is running;the error-detail contains the SRL numbers2 of the two SRLs in the form xxyy (where xx is the SRL that requires the fixup to the running yy SRL).
Table 28 Summary of NEWPROCESS[NOWAIT] error and error-detail Values (continued) error Description (including error-detail values, when applicable) 43 The shared run-time library (SRL) either has a gateway (GW) table but no callable procedures or has gateways that are not in the (GW) area. 50 The shared run-time library (SRL) is not executable. Either it was not linked with the nld utility or it was not linked correctly.
library” is the set of implicit DLLs. At load time, symbols are bound to the first definition found in the search list of the program. If no library specification is provided (priority bit 1 is zero, or library-file is blank), the process runs with whatever library file, if any, is specified in the program file. The library-file parameter can specify either a file name, or that no library should be used.
are selected from this set of names. For more information about reserved process names, see Appendix B: Reserved Process Names. • Creator access ID (CAID) and process access ID (PAID) The creator access ID of the new process is always the same as the process access ID of the creator process.
Batch Processing Considerations NOTE: The job ancestor facility is intended for use by the NetBatch product. Other applications that use this facility might be incompatible with the NetBatch product. • When the process being created is part of a batch job, NEWPROCESS[NOWAIT] sends a job process creation message to the job ancestor of the batch job. (See the discussion of job ancestor in the Guardian Programmer's Guide.
◦ Login name ◦ Current working directory (cwd) ◦ Maximum file size ◦ Default OSS file security No other OSS process attribute is inherited by the new process. • OSS file opens in the calling process are not propagated to the new process. Examples CALL NEWPROCESS ( pfile^name, , , , process^id, error ); CALL NEWPROCESSNOWAIT ( pfile^name , ! Priority. , ! Memory pages. , ! Processor.
NEXTFILENAME Procedure (Superseded by FILENAME_FINDNEXT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The NEXTFILENAME procedure is used to obtain the name of the next disk file on a designated volume.
\sysnum volname (blank-fill) file-name[4:11] =subvol-name (blank-fill) To return the name of the next file in alphabetic sequence: file-name[0:3] $volname (blank-fill) or \sysnum volname (blank-fill) file-name[4:7] subvol-name (blank-fill) file-name[8:11] file-id (blank-fill) When file-name returns, it contains the next file name, if any, in alphabetic sequence. Returned Value INT A file-system error code that indicates the outcome of the call.
NO^ERROR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The NO^ERROR procedure is called internally by sequential I/O (SIO) procedures. Error handling and retries are implemented within the SIO procedure environment by the NO^ERROR procedure. If the file is opened by OPEN^FILE, then the NO^ERROR procedure can be called directly for the file-system procedures.
good-error-list input INT:ref:* is a list of error numbers; if one of the numbers matches the current error, no-retry is returned as nonzero (no retry). The format of good-error-list, in words, is: [0] Number of error numbers in list {0:n} [1] Good error number . . . [n] Good error number retryable input INT:value is used to determine whether certain path errors should be retried.
Example INT GOOD^ERROR [ 0:1 ] := [ 1, 11 ]; ! nonexistent record. . . .
NODE_GETCOLDLOADINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The NODE_GETCOLDLOADINFO_ procedure retrieves the name of the OSIMAGE file from which the specified node was system loaded. NODE_GETCOLDLOADINFO_ assists subsystems that look for their configuration files on $SYSTEM.SYSnn, or that must know the name of the system-load subvolume.
nodename:length input:input STRING .EXT:ref:*, INT:value if supplied and length is not 0, specifies the name of the node for which system-load information is to be returned. If used, the value of nodename must be exactly length bytes long. The default is the name of the local node. Returned Value INT Outcome of the call: 0 File name successfully retrieved. 1 (reserved) 2 Parameter error. 3 Bounds error. 4 Unable to communicate with node.
NODENAME_TO_NODENUMBER_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The NODENAME_TO_NODENUMBER_ procedure converts a node name (system name) to the corresponding node number (system number). It can also be used to obtain the number of the caller's node.
Returned Value INT A file-system error code that indicates the outcome of the call.
NODENUMBER_TO_NODENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The NODENUMBER_TO_NODENAME_ procedure converts a node number (system number) to the corresponding node name (system name). It can also be used to obtain the name of the caller's node.
ldevnum output INT(32) .EXT:ref:1 returns the logical device number of the line handler to the specified node. If the specified node is the local node, ldevnum returns 32767. If error is nonzero, ldevnum is undefined. Returned Value INT A file-system error code that indicates the outcome of the call. Considerations If the value specified for nodenumber does not designate a node that is known to the local system, an error value of 18 is returned.
NSK_FLOAT_IEEE TO TNS Procedures NSK_FLOAT_IEEE32_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Summary The NSK_FLOAT_IEEE TO TNS procedures convert numbers in the IEEE floating-point format to numbers in the TNS floating-point format.
Parameters For NSK_FLOAT_IEEE32_TO_TNS32_: IEEE_Data input INT .EXT:ref (NSK_float_ieee32) is the 32-bit IEEE floating-point number. TNS_Data output INT .EXT:ref (NSK_float_tns32) is the 32-bit TNS floating-point number. For NSK_FLOAT_IEEE32_TO_TNS64_: IEEE_Data input INT .EXT:ref (NSK_float_ieee32) is the 32-bit IEEE floating-point number. TNS_Data output INT .EXT:ref (NSK_float_tns64) is the 64-bit TNS floating-point number. For NSK_FLOAT_IEEE64_TO_TNS64_: IEEE_Data input INT .
The following table indicates which procedures can produce which errors: Conversion Over-flow Under-flow In-exact Was_ Inf Was_NaN IEEE64 to TNS64 YES YES YES YES YES IEEE64 to TNS32 YES YES YES YES YES IEEE32 to TNS32 YES NO YES YES YES NOTE: For IEEE32-to-TNS32 conversion, overflow can occur only if the input is infinite or a NaN. Considerations • These procedures are usable by both TNS floating-point-format callers and IEEE floating-point-format callers.
error := NSK_FLOAT_IEEE64_TO_TNS64_( before, after ); if ($int(error) LAND $int(NSK_FLOAT_TNS_OVERFLOW)) then return( 2D ); -- 2 for overflow (out of range) return( 0D ); -- 0 for no errors end; NSK_FLOAT_IEEE TO TNS Procedures 877
NSK_FLOAT_TNS TO IEEE Procedures NSK_FLOAT_TNS32_TO_IEEE32_ Procedure NSK_FLOAT_TNS32_TO_IEEE64_ Procedure NSK_FLOAT_TNS64_TO_IEEE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Summary The NSK_FLOAT_TNS TO IEEE procedures convert numbers in the TNS floating-point format to numbers in the IEEE floating-point format.
Parameters For NSK_FLOAT_TNS32_TO_IEEE32_: TNS_Data input INT .EXT:ref (NSK_float_tns32) is the 32-bit TNS floating-point number. IEEE_Data output INT .EXT:ref (NSK_float_ieee32) is the 32-bit IEEE floating-point number. For NSK_FLOAT_TNS32_TO_IEEE64_: TNS_Data input INT .EXT:ref (NSK_float_tns32) is the 32-bit TNS floating-point number. IEEE_Data output INT .EXT:ref (NSK_float_ieee64) is the 64-bit IEEE floating-point number. For NSK_FLOAT_TNS64_TO_IEEE64_ TNS_Data input INT .
The following table indicates which procedures can produce which errors: Conversion Overflow Underflow Inexact TNS64 to IEEE64 NO NO YES TNS32 to IEEE64 NO NO NO TNS32 to IEEE32 YES YES YES Considerations For description of considerations for this procedure, see the NSK_FLOAT_IEEE TO TNS procedures Considerations (page 876). Examples C Example #include #include
NUMBEREDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The NUMBEREDIT procedure renumbers the lines of an EDIT file that are in a specified range. You can specify the new starting number and increment for the range of lines to be renumbered. NUMBEREDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
last input INT(32):value specifies 1000 times the line number of the last line in the range of lines to be renumbered. If a negative value is specified, the line number of the last line in the file is used. start input INT(32):value specifies 1000 times the line number to be assigned to the first renumbered line. If this parameter is omitted, the old line number is retained for the first renumbered line unless first is a negative value, in which case 1000 is used for start.
NUMIN Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The NUMIN procedure converts the ASCII characters used to represent a number into the signed integer value for that number.
status output INT:ref:1 returns a number that indicates the outcome of the conversion. The values for status are: 1 Nonexistent number (string does not start with "+," "-," "%," or numeric). 0 Valid conversion. -1 Invalid integer (number cannot be represented in 15 bits) or bad character in ascii-num. Returned Value BADDR ‘G'[0] relative string address of the first character in ascii-num not used in the conversion.
NUMOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The NUMOUT procedure converts unsigned integer values to their ASCII equivalents. The result is returned right-justified in an array. Any preceding blanks are zero filled.
Considerations If width is too small to contain the number, the most significant digits are lost. Related Programming Manual For programming information about the NUMOUT utility procedure, see the Guardian Programmer's Guide.
11 Guardian Procedure Calls (O) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter O. Table 29 lists all the procedures in this section.
OBJFILE_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Attribute Codes and Value Representations Considerations Example Summary The OBJFILE_GETINFOLIST_ procedure obtains information about the object file or user library file of the calling process. NOTE: OBJFILE_GETINFOLIST_ does not support dynamic-link libraries.
If the requested information doesn't fit in ret-values-list, the procedure returns an error value of 1 and an error-detail value of 563 (buffer too small). No information is returned. The maximum value for this parameter is 1024. ret-values-list output INT .EXT:ref:* contains ret-values-len bytes of returned information. The values parallel the items in ret-attr-list. Each value begins on a word boundary. For details, see Attribute Codes and Value Representations (page 890).
3 Bounds error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left. 4 Invalid attribute code specified; error-detail contains the attribute code that is unknown to OBJFILE_GETINFOLIST_. 5 The process does not have a user library. 6 The process header cannot be found.
4: Binder length (for TNS object files only) is the length in bytes of the Binder region of the file. A value of 0 is returned if the file has no Binder region. If the object file is a native object file, 0D is returned. 5: Inspect on indicates whether the debugger for the file is the Inspect debugger or Debug. A value of 0 indicates Debug; a value of 1 indicates the Inspect debugger. 6: High PIN indicates whether the process can run with a high PIN.
16: Buffer size for attribute code 17 (for non-PIC native object files only) is the size of the buffer, in bytes, for the array returned in attribute 17. 0 indicates that the object file does not use shared run-time libraries.
OLDFILENAME_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The OLDFILENAME_TO_FILENAME_ procedure converts a file name in the C-series internal file-name format to a file name in the D-series file-name format. See Appendix D: File Names and Process Identifiers for descriptions of C-series and D-series file names.
Considerations • The output file name always includes a node name regardless of whether the input name was in network form. Note that the node name in the output is independent of the =_DEFAULTS DEFINE, as is the node name in the input. This is because the default node name in an internal file name is the node that the caller is running on, not the value in the =_DEFAULTS DEFINE.
OLDSYSMSG_TO_NEWSYSMSG_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The OLDSYMSG_TO_NEWSYSMSG_ procedure converts a C-series format system message to its D-series equivalent. See Considerations (page 896) for a list of the messages that this procedure accepts and produces.
error-detail output INT .EXT:ref:1 for some returned errors, contains additional information. See Returned Value. Returned Value INT Result of the check: 0 Message successfully converted. 1 File-system error; error-detail contains the file-system error number. 2 Parameter error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Terminal Considerations Interprocess Communication Considerations DEFINE Considerations Safeguard Considerations OSS Considerations Messages Example Related Programming Manuals Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development.
filenum output INT:ref:1 returns a number used to identify the file in subsequent system calls. A -1 is returned if OPEN fails. flags input INT:value specifies certain attributes of the file. If omitted, all fields are set to 0. The bit fields in the flags parameter are defined in Table 30. Table 30 OPEN flags Parameter Flag Flag in Octal Meaning <0> %100000 For disk files, if this bit is 1, specifies the “last open time” attribute of the file being opened is not updated by this open.
sync-or-receive-depth input INT:value The purpose of this parameter depends on the type of device being opened: Disk file specifies the number of nonretryable (that is, write) requests whose completion the file system must remember. A value of 1 or greater must be specified to recover from a path failure occurring during a write operation.
primary-process-id and primary-filenum are supplied only if the open is by the backup process of a process pair, the file is currently open by the primary process, and the checkpointing facility is not used. Both parameters must be supplied. seq-block-buffer-id input INT:ref:1 is a 16-bit value, the address of which identifies the sequential block buffer to be shared, if sequential block buffering is used and if sharing is desired.
Considerations • File numbers Within a process, the file numbers are unique. The lowest numeric file number is 0 and is reserved for $RECEIVE. Remaining file numbers start at 1. The lowest available file number is always assigned. Once a file is closed, its file number becomes available, and a subsequent open can reuse that file number.
The specific limit for a file is dependent on the file's device type: • Disk Files Cannot exceed 65,279 opens per disk Process Defined by process (see discussion of controlling openers in the Guardian Programmer's Guide) $0 Unlimited opens $0.#ZSPI 128 concurrent opens permitted $OSP 10 times the number of subdevices (up to a maximum of 83 subdevices) $RECEIVE One open per process permitted Other Varies by subsystem Nowait opens—errors If a process file is opened in a nowait manner (flags.
• Disk file open—security check When a disk file open is attempted, the system performs a security check. The accessor's (that is, the caller's) security level is checked against the file security level for the requested access mode, as follows: for read access: read security level is checked for write access: write security level is checked for read-write access: read and write security levels are checked A file has one of seven levels of security for each access mode.
If you are using the Safeguard product, this security information might not apply. • Tape file open—access mode The file system does not enforce read-only or write-only access for unlabeled tape, even though no error is returned if you specify one of these access modes when opening a tape file. • File open—exclusion and access mode checking When a file open is attempted, the requested access and exclusion modes are compared with those of any opens already granted for the file.
Disk File Considerations • Maximum number of concurrent nowait operations The maximum number of concurrent nowait operations permitted for an open of a disk file is one. Attempting to open a disk file and specify a value greater than 1 returns an error indication. A subsequent call to FILEINFO or FILE_GETINFO_ shows that an error 28 occurred.
• Queue files If the READUPDATELOCK[X] operation is to be used, the sync-or-receive-depth parameter must be 0. A separate open may be used for operations with sync-or-receive-depth >0. Sequential block buffering cannot be used. • Format 2 key-sequenced files with increased limits not supported on legacy 514-byte sector disks OPEN does not support the open of format 2 key-sequenced files with increased limits (in H06.28/J06.17 RVUs with specific SPRs and later RVUs) on legacy 514-byte sector disks.
on a remote node that has a process name consisting of more than five characters will fail with an error 20. DEFINE Considerations The file-name parameter can be a DEFINE name; OPEN will use the file name given by the DEFINE as the object to be opened. If a CLASS TAPE DEFINE without the DEVICE attribute is referenced, a specific tape drive will be selected. A DEFINE of CLASS TAPE has other effects when supplied to OPEN; see Appendix E: DEFINEs for further information about DEFINEs.
OPEN^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations EDIT File Considerations Level-3 Spooling Considerations Example Related Programming Manual Summary The OPEN^FILE procedure permits access to a file when using sequential I/O (SIO) procedures.
following a process startup. The size of the file control block differs between TNS processes and native processes. file-fcb input INT:ref:* is an array of FCBSIZE or FCBSIZE^D00 words for use by the SIO procedures. The file FCB uniquely identifies this file to other SIO procedures. The file FCB must be initialized with the name of the file to be opened before OPEN^FILE is called. The size of the file control block differs between TNS processes and native processes.
These literals can be combined using signed addition because bit 0 is not used: ABORT^OPENERR KEEP^LASTOPENTIME PURGE^DATA ABORT^XFERERR LEVEL3^SPOOL^ENABLE READ^TRIM AUTO^CREATE MUSTBENEW VAR^FORMAT AUTO^TOF NOWAIT WRITE^FOLD BLOCKED OLD^RECEIVE WRITE^PAD CRLF^BREAK PRINT^ERR^MSG WRITE^TRIM For the meanings of literals used with flags, see Considerations (page 911). Literal declarations are contained in the file $SYSTEM.SYSTEM.GPLDEFS.
Considerations • Specifics of AUTO^TOF If AUTO^TOF is ON, a top-of-form control operation is performed to the file when both (1) the file being opened is a process or a line printer, and (2) write access is specified. • When read/write access is not permitted If the file is an EDIT file or if blocking is specified, either read or write access must be specified for the open to succeed. Read/write access is not permitted.
CRLF^BREAK (%40000D) Carriage return/line feed (CR/LF) on BREAK; defaults to ON. If ON and BREAK is enabled, a CR/LF is written to the terminal when BREAK is entered. KEEP^LASTOPENTIME (%400000D) Keep last open time; defaults to OFF. If ON and open access to a disk file is read only, the “time of last open” file attribute is not updated by this open. If OFF, the “time of last open” file attribute is updated. This flag is ignored if the file is not a disk file or if open access is not read only.
compared to the same file managed by SIO before D20. The file is not actually larger, as the same amount of disk space is allocated in both cases. The difference is that in the newer version, the last part of each new extent is immediately put into use. • SIO always performs buffered I/O, using the disk process buffering mechanism to enhance performance, when writing to an EDIT file. You can force SIO to flush buffered data to disk by calling WRITE^FILE and specifying a write-count of -1.
OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary NOTE: The OPENEDIT procedure is supported for compatibility with previous software. For new development, the OPENEDIT_ procedure should be used instead.
flags input INT:value specifies the value that is passed to the flags parameter of the OPEN procedure if OPENEDIT opens the file. These conditions apply: • If OPENEDIT opens the file and if the flags parameter is omitted, the value %002001 (read-only, shared access, nowait mode) is used.
16 File has not been opened, wrong file type; indicates that the file is not an EDIT file (that is, the file type is not unstructured or the file code is not 101 or 102). 31 Unable to obtain buffer space; indicates that the file's directory does not fit into IOEdit's extended data segment and OPENEDIT_ is unable to enlarge the segment.
OPENEDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The OPENEDIT_ procedure allocates and initializes data blocks in the EDIT file segment (EFS) so that the specified file can be accessed later by the IOEdit procedures. It optionally creates and opens the specified file through the file system.
and that filenum is the number returned by the file system to identify the open file. In this case, OPENEDIT_ only verifies that the file is an EDIT file and creates the internal data structures necessary for subsequent IOEdit operations on the file. If filenum is a negative value or if the file does not exist, OPENEDIT_ opens the file by calling FILE_OPEN_ (after calling FILE_CREATE_, if necessary), and then creates the internal IOEdit data structures.
sync-depth input INT:value specifies the sync depth value to be passed to the FILE_OPEN_ procedure if OPENEDIT_ opens the file. If this parameter is omitted, 0 is used. For a detailed description of this parameter, see the sync-or-receive-depth parameter under FILE_OPEN_ Procedure (page 457) . write-thru input INT:value if present and not 0, specifies that each call to an IOEdit procedure that changes the content of the file must fully update the disk copy of the file.
Considerations • The caller must set the filenum parameter to an appropriate value before each call to OPENEDIT_, because its value might be changed upon return. • If the file is already open at the time of the call to OPENEDIT_, the access, exclusion, nowait, sync-depth, and write-thru parameters to OPENEDIT_ are ignored. • OPENEDIT_ sets the file's current record number to -1 and resets the line number increment to 1 (that is, it resets the record number increment to 1000).
OPENER_LOST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The OPENER_LOST_ procedure examines a system message and searches an open table to determine if an opener has been lost. An opener might be lost due to a processor or system failure that is reported in the system message. An opener is a process that has opened the process that is calling OPENER_LOST_.
-100 Remote processor failure. -110 Connection to remote system lost. If any other system message is supplied, an error is returned and the index is not advanced. length is the length in bytes of the message. table input INT .EXT:ref:* points to the beginning of the open table to be searched.
Considerations • Determining if an opener has been lost The OPENER_LOST_ procedure reports that an opener has been lost if: • ◦ The connection to a remote system is lost and the process was running in that system. ◦ A remote processor has failed and the process was running in that processor. ◦ A local processor has failed and the process was running in that processor. The open table The open table is created and maintained by the caller.
Example index := -1; ! initialize table ! index.
OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The OPENINFO procedure obtains information about the opens of one disk file or of all the files on a disk device, or of certain nondisk devices.
pricrtpid output INT:ref:4 is the process ID of the (primary) process that has the file open. backcrtpid output INT:ref:4 is the process ID of the backup process of a process-pair that has the file open, or is all zeros if there is no open by a backup. accessmode output INT:ref:1 is the access mode with which the file is open. The codes are: 0 read-write 1 read only 2 write only exclusion output INT:ref:1 is the exclusion mode with which the file is open.
validmask output INT:ref:1 returns a value indicating which of the information parameters had valid information returned. Each parameter has a corresponding bit in this value set to true if the parameter is valid for the device, as follows: <0> pricrtpid <1> backcrtpid <2> accessmode <3> exclusion <4> syncdepth <5> file-name <6> accessid Returned Value INT A file-system error code that indicates the outcome of the call. Error 1 (EOF) indicates there are no further opens.
Example DEVICE^NAME^PADDED ':=' ["$DEVICE ",8*[" "]]; NUM := 0; DO -- Get OPENINFO for the device BEGIN ERROR := OPENINFO( DEVICE^NAME^PADDED, NUM, PCRTPID, BCRTPID, ACCESSMODE, EXCLUSION, SYNC, FILENAME, ACCESSID ); IF ERROR = 0 !SUCCESS! THEN BEGIN -- Process (filter/sort) OPEN-record END; END -- Get OPENINFO for the device UNTIL ERROR <> 0 !SUCCESS!; IF ERROR = 2 !INVALID OPERATION! THEN BEGIN -Device doesn't support OPENINFO END ELSE IF ERROR <> 1 !END OF FILE! THEN BEGIN -- File-system error/resource p
OSS_PID_NULL_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value OSS Considerations Summary The OSS_PID_NULL_ procedure returns a null OSS process ID. Syntax for C Programmers #include __int32_t OSS_PID_NULL_ ( void ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int.
12 Guardian Procedure Calls (P) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter P. Table 33 lists all the procedures in this section. Table 33 Procedures Beginning With the Letter P PACKEDIT Procedure PATHNAME_TO_FILENAME_ Procedure POOL_CHECK_ Procedure POOL_DEFINE_ Procedure POOL_GETINFO_ Procedure POOL_GETSPACE_ Procedure POOL_GETSPACE_PAGE_ Procedure POOL_PUTSPACE_ Procedure POOL_RESIZE_ Procedure POOL32_... and POOL64_...
Table 33 Procedures Beginning With the Letter P (continued) PROCESS_MONITOR_NET_ Procedure PROCESS_MONITOR_NEW_ Procedure PROCESS_MONITOR_VCORE_ Procedure PROCESS_SETINFO_ Procedure PROCESS_SETSTRINGINFO_ Procedure PROCESS_SPAWN_ Procedure PROCESS_STOP_ Procedure PROCESS_SUSPEND_ Procedure PROCESSACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) PROCESSFILESECURITY Procedure (Superseded by PROCESS_SETINFO_ Procedure or PROCESS_GETINFOLIST_ Procedure) PROCESSHANDLE_COMPARE_ Procedure PROCESSH
PACKEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The PACKEDIT procedure converts a line image from unpacked format into EDIT packed line format. The input value is a text string that can include sequences of blank characters; the returned value is the same text in packed format with blank compression codes.
packed-limit input INT:value specifies the length in bytes of the string variable packed-line. packed-length output INT .EXT:ref:1 returns the actual length in bytes of the value returned in packed-line. If packed-line is not large enough to contain the value that is the output of the conversion, packed-length returns a value of -1.
PATHNAME_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value OSS Considerations Example Related Programming Manual Summary The PATHNAME_TO_FILENAME_ procedure converts an OSS pathname to a Guardian file name. For a description of the OSS pathname syntax, see Appendix D: File Names and Process Identifiers.
length output INT .EXT:ref:1 returns the length in bytes of the fully qualified Guardian file name returned in filename. If error returns 563 (buffer too small) due to filename being to small to contain the name, length returns the actual length of the name. info-flags output INT .EXT:ref:1 contains additional information about the file. info-flags is returned as a bit mask defined as: Reserved. <0:14> <15> =1 The specified file is a Guardian file. =0 The specified file is an OSS file.
file has the form /G/volname/#number which corresponds to the Guardian name $volume.#number. The conversion takes place as follows: ◦ The initial "/G/" is removed. ◦ The remaining slash separators (/) are replaced by periods. ◦ If the current directory symbol (.) is part of the pathname it is safely ignored. ◦ If the parent directory symbol (..) is part of the pathname, the first element to the left is deleted. ◦ A leading dollar sign ($) is added for part of the Guardian volume name.
POOL_CHECK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_CHECK_ procedure checks the internal pool data structures and returns error information.
block output EXTADDR .EXT:ref:1 is defined for these values of error: error block 11 Address of the valid allocated block that precedes the address where the corruption is detected. If the corruption is detected in the first block, then block is -4D. 12 Address of the valid free block that precedes the address where the corruption is detected. If the corruption is detected in the first block, then block is -4D. block-size output INT .
POOL_DEFINE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_DEFINE_ procedure designates a portion of a user's stack, global data or a data segment for use as a pool. It initializes the pool for use by the other procedures in the POOL_... family. NOTE: The POOL_... procedures are superseded for native TNS/E callers; see POOL32_... and POOL64_... Procedures (page 953).
is always equal to the address specified for pool plus the value of pool-size. Pool space overhead and adjustments for alignment do not cause the pool to extend past this boundary. alignment input INT:value specifies the alignment of blocks allocated from the pool. 0 8 byte alignment 4 4 byte alignment 8 8 byte alignment 16 16 byte alignment (the default alignment) On TNS processors, an eight-byte alignment is recommended.
• Dynamic memory allocation Several Guardian procedures support the creation of memory pools and the dynamic allocation of variable-sized blocks from a pool. The calling program provides the memory area to be used as the pool and then calls the POOL_DEFINE_ procedure to initialize the pool. The pool can reside in the user data stack or in an extended data segment. The pool procedures accept and return extended addresses that apply to both the stack and extended memory.
POOL_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_GETINFO_ procedure returns information about the specified pool.
error-detail output INT .EXT:ref:1 for some returned errors, contains additional information. See Returned Value (page 944). avail-pool-size output INT(32) .EXT:ref:1 is the available space in bytes in the pool, not including the pool header. Note that the value of the pool-size parameter specified in the POOL_DEFINE_ procedure is larger than this value because it includes the pool header. curalloc output INT(32) .
tag-size output INT .EXT:ref:1 is the size in bytes of one of the tags used to mark the free or allocated blocks. Returned Value INT Outcome of the call: 0 No error. 2 Required parameter missing. error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left. 3 Bounds error. error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left. 9 Corrupt pool header.
POOL_GETSPACE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_GETSPACE_ procedure obtains a block of memory from a buffer pool.
error output INT .EXT:ref:1 indicates the outcome of the call: 0 No error. 2 Required parameter missing. 4 Invalid size. block-size is not within the valid range. 9 Corrupt pool header. 10 Unable to allocate space. Returned Value INT(32) The extended address of the first byte in the memory block obtained if the operation is successful, and %37777000000D if an error occurs. Considerations NOTE: There are additional considerations for privileged callers.
POOL_GETSPACE_PAGE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL_GETSPACE_PAGE_ procedure obtains a block of memory from a buffer pool. The memory is aligned on a page boundary and the space allocated is a multiple of a page size. The POOL_GETSPACE_PAGE_ procedure is supported only in J-series and H-series RVUs.
Returned Value INT(32) The extended address of the first byte in the memory block obtained if the operation is successful, and %37777000000D if an error occurs.
POOL_PUTSPACE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_PUTSPACE_ procedure returns a block of memory to a buffer pool. Syntax for C Programmers #include short POOL_PUTSPACE_ ( short *pool ,short *block ); Syntax for TAL Programmers error := POOL_PUTSPACE_ ( pool ,block ); ! i ! i Parameters pool input INT .
Considerations POOL_GETSPACE_ and POOL_PUTSPACE_ do not check pool data structures on each call. A process that destroys data structures can fail on a call to POOL_GETSPACE_ or POOL_PUTSPACE_: a TNS Guardian process can get a bounds violation trap (trap 0); an OSS or native process can receive a SIGSEGV signal. Example error := POOL_PUTSPACE_ ( pool, pblock ); ! put a block obtained from POOL_GETSPACE_ back into ! the pool obtained from POOL_DEFINE_.
POOL_RESIZE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The POOL_RESIZE_ procedure changes the size of a pool that was initialized by the POOL_DEFINE_ procedure. Syntax for C Programmers #include .
Returned Value INT Outcome of the call: 0 No error. 2 Required parameter missing. 3 Bounds error. pool is in a read-only segment, or new-pool-size is larger than the available space. 4 Invalid size. block-size is not within the valid range. 9 Corrupt pool header. 11 Corrupt allocated block: Data is probably written beyond the allocated block or the block has already been returned. 12 Corrupt free list blocks. Data is probably written into a returned block. 13 Unable to shrink pool.
POOL32_... and POOL64_... Procedures The POOL64_... procedures manage a 64-bit pool. The similar POOL32_... procedures manage a 32-bit pool. The two sets of procedures use the same pool-management algorithms. The differences are: • The POOL64_... procedures use 64-bit addresses, so the pool can be anywhere in 64-bit address space (which includes 32-bit address space). The POOL32_... procedures use 32-bit addresses, so the pool must be within 32-bit address space.
POOL64_AUGMENT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_AUGMENT_ procedure adds a secondary memory segment to an existing pool. The caller must first allocate the memory space for the new segment. A pool contains a primary segment, established initially by POOL64_DEFINE_, and may contain secondary segments established by POOL64_AUGMENT_. Pool segments are generally not contiguous.
Returned Value INT(32) Outcome of the call: 0 POOL64_OK Successful completion. 5 POOL64_ALIGN The new segment area is not 16 byte aligned. 3 POOL64_BOUNDS The memory being augmented is not within this user's address bounds. 20 POOL64_INVALIDADDRESS Pool address is outside the acceptable address range. 24 POOL64_SEGOVERLAP Some or all of the new segment overlaps the existing pool. 101 POOL64_BAD_POOL Pool is uninitialized or corrupted. These values are defined in kpool64.
POOL64_CHECK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Summary The POOL64_CHECK_ procedure checks the internal pool data structures and returns error information about the pool. If the pool contains no errors, a return code of POOL64_OK is returned; otherwise when the first error is encountered, checking is stopped and the error is returned. Syntax for C Programmers #include
POOL64_CHECK_SHRINK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Returnable Bytes and Segment Combinations Summary The POOL64_CHECK_SHRINK_ procedure provides information for how to reduce the footprint of the pool. It returns the number of returnable bytes, and the number of returnable segments for the pool specified by the caller. Syntax for C Programmers #include
Returned Value INT(32) Outcome of the call: 0 POOL64_OK Successful completion. 101 POOL64_BAD_POOL Pool is uninitialized or corrupted. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption.
POOL64_DEFINE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The POOL64_DEFINE_ procedure designates an allocated 64-bit memory address range to use as the primary segment of a pool. The caller must allocate the memory space for the pool prior to the call. For availability of the POOL64_... procedures, see POOL32_... and POOL64_... Procedures (page 953). Syntax for C Programmers #include
pool_options input INT(32) The values are defined in kpool64.h for C and KPOOL64 for pTAL. The only value valid for unprivileged callers is: POOL64Default (0) NOTE: The POOL64 procedures are designed for use in 64-bit address space. 32-bit address space is a subset of 64-bit address space, so a 64-bit pool can occur in either 32-bit or 64-bit flat segments. The POOL64_... and POOL32… procedures are not recommended for use in selectable data segments.
(void _ptr64* _ptr64*)&poolBase); if (error != SEGMENT_OK) { printf("SEGMENT_ALLOCATE64_ error %d, %d\n", error, detail); exit(EXIT_FAILURE); } poolResult = POOL64_DEFINE_(poolBase, poolSize, POOL64Default); if (error != POOL64_OK) { printf("POOL64_DEFINE_ error %d\n",poolResult); exit(EXIT_FAILURE); } printf("Pool64 created at %#llx for %#llx bytes\n", poolBase, poolSize); } POOL64_DEFINE_ Procedure 961
POOL64_DIMINISH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_DIMINISH_ procedure releases an empty secondary segment (if one exists) from an existing pool. If more than one secondary segment is empty, the one released is implementation-dependent. If a segment is released, a pointer to the start of the segment is returned along with the size of the released segment.
Returned Value INT(32) Outcome of the call: 0 POOL64_OK Successful completion. 22 POOL64_CANTDIMINISH This is a single segment pool. 23 POOL64_NOEMPTYSEG No empty segments are available to be released. 101 POOL64_BAD_POOL Pool is uninitialized or corrupted. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption.
POOL64_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_GET_ procedure allocates an element from the specified pool. The size parameter specifies the amount of memory requested. Upon successful allocation, the base address is a multiple of 16. The allocated size may be slightly larger than required. Syntax for C Programmers #include
10 POOL64_NOSPACE Not enough memory is present in the pool to satisfy the request. 101 POOL64_BADPOOL Pool is uninitialized or corrupted. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption. Returned Value EXT64ADDR The starting address of the element obtained from the specified pool. A value of 0xFFFFFFFFFFFC0000 is returned on error.
POOL64_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for pool_info Summary The POOL64_GETINFO_ procedure returns information about the specified pool. The pool_info_length parameter specifies the size of the pool64_info structure that is stored at the pool_info address. If pool_info_length is not large enough an error is returned indicating that not all of the pool information is being returned.
Returned Value INT(32) Outcome of the call: 0 POOL64_OK Successful completion. 26 POOL64_NOINFO The size provided is not large enough to store any pool information. 25 POOL64_MOREINFO More information available than would fit in the pool_info_length provided. 101 POOL64_BAD_POOL Pool is uninitialized or corrupted. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Structure Definitions for pool_info The NSK_POOL64_INFO structure is defined in kpool64.h for C and KPOOL64 for pTAL.
POOL64_PUT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_PUT_ procedure frees (returns to the designated pool) an element previously allocated by POOL64_GET_. Syntax for C Programmers #include uint32 POOL64_PUT_ ( NSK_POOL64_PTR pool_ptr ,void _ptr64 *element_ptr ); Syntax for TAL Programmers ?SOURCE $SYSTEM.SYSTEM.KPOOL64 result := POOL64_PUT_ ( pool_ptr ,element_ptr ); ! i ! i Parameters pool_ptr input INT .
The element_ptr parameter is not a multiple of 16. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption. Two such results may indicate a programming error with respect to the element specified by element_ptr: POOL64_POOLTAGMISMATCH usually implies the program has written beyond the allocated element; POOL64_BADHEADER often results if the element has already been freed.
POOL64_REALLOC_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_REALLOC_ procedure changes the size of the block of memory pointed to by the element parameter to the number of bytes specified by the newSize parameter and returns a pointer to the block of memory. The contents of the block remain unchanged up to the lesser of the old and new sizes. If necessary, a new block is allocated, and data is copied to it.
newSize input INT(64) indicates the new size requested for the pool element. error output INT(32) .EXT64 indicates the outcome of the call. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption. 0 POOL64_OK Successful completion. 2 POOL64_PARAMETER Required parameter missing or invalid. pool must be specified. 4 POOL64_INVALIDSIZE Size requested is larger than the maximum possible request.
POOL64_RESET_MAX_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Summary The POOL64_RESET_MAX_ procedure resets the max_… accumulators in the designated pool to the current value of the measured quantity. For example, it sets the max_alloc accumulator to the current value of alloc. These accumulators are reported by the POOL64_GETINFO_ Procedure (page 966). Syntax for C Programmers #include
POOL64_RESIZE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Summary The POOL64_RESIZE_ procedure shrinks or expands the size of a single-segment pool within the same address space. The memory allocation for expanding the pool is the responsibility of the caller before calling this procedure. If the pool has a secondary segment, this procedure fails. If shrinking the pool and a chunk is in use above the address of the new size, the resize fails.
5 POOL64_ALIGN The new_pool_size provided is not 16 byte aligned. 13 POOL64_CANTSHRINK Memory above the new_pool_size is allocated. 21 POOL64_CANTRESIZE This pool has at least one secondary segment, resize is not allowed. 101 POOL64_BAD_POOL Pool is uninitialized or corrupted. These values are defined in kpool64.h for C and KPOOL64 for pTAL. Other results indicate an error within the pool structure, probably corruption.
POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Related Programming Manuals Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The POSITION procedure positions by primary key within relative and entry-sequenced files. For unstructured files, the POSITION procedure specifies a new current position.
record-specifier input INT(32):value is the four-byte value that specifies the new setting for the current-record and next-record pointers. Relative Files record-specifier is a four-byte record-num. -2D specifies that the next write occur at an unused record position. -1D specifies that subsequent writes be appended to the end-of-file location. Unstructured Files record-specifier is a four-byte relative-byte-addr. -1D or -2D specifies that subsequent writes be appended to the EOF location.
can be either an odd or even value. (You set the odd unstructured attribute with the FILE_CREATE_, FILE_CREATELIST_, or CREATE procedure, or with the File Utility Program (FUP) SET and CREATE commands.) For even unstructured files (that is, files created with the odd unstructured attribute not set), the record-specifier parameter must be an even byte address, or the operation fails with file-system error 2.
POSITIONEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The POSITIONEDIT procedure sets the next record number to a specified value for a specified file. POSITIONEDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
Example In this example, POSITIONEDIT sets the next record number to indicate line 500 in the specified file. INT(32) next-record-number := 500000D; . . error := POSITIONEDIT ( filenumber, next-record-number ); Related Programming Manual For programming information about the POSITIONEDIT procedure, see the Guardian Programmer's Guide.
PRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure or PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PRIORITY procedure enables a process to examine or change its initial priority.
Considerations • A caller of PRIORITY executing in privileged mode can set its priority to a value greater than 199. However, if such a process has a priority greater than that of the memory-manager process and gets a memory page fault, the call to PRIORITY fails: a Guardian TNS process gets a "no memory available" trap (trap 12); an OSS or native process receives a SIGNOMEM signal. • The current priority rather than the initial priority is returned.
PROCESS_ACTIVATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Safeguard Considerations OSS Considerations Related Programming Manual Summary The PROCESS_ACTIVATE_ procedure returns a suspended process or process pair to the ready state. A process is suspended by calling the PROCESS_SUSPEND_ or SUSPENDPROCESS procedure, or by entering a TACL SUSPEND command.
Returned Value INT Outcome of the call: 0 Process successfully activated. 2 Process is already in the ready state. 11 Process does not exist. 48 Security violation. 201 Unable to communicate with processor where the process is running. Considerations • Procedure use You can use PROCESS_ACTIVATE_ to activate any suspended process or process pair, even if it was suspended by a call to SUSPENDPROCESS.
Related Programming Manual For programming information about the PROCESS_ACTIVATE_ procedure, see the Guardian Programmer's Guide.
PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value General Considerations Nowait Considerations Compatibility Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations File Privileges Considerations Example Related Programming Manuals Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new deve
Syntax for C Programmers #include short PROCESS_CREATE_ ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ const char *program-file ] short program-file-length ] const char *library-file ] short library-file-length ] const char *swap-file ] short swap-file-length ] const char *ext-swap-file ] short ext-swap-file-length ] short priority ] short processor ] short *processhandle ] short *error-detail ] short name-option ] const char *name ] short name-le
Syntax for TAL Programmers error := PROCESS_CREATE_ ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ • ! input/output program-file:progam-file-length ] ! library-file:library-file-length ] ! swap-file:swap-file-length ] ! ext-swap-file:ext-swap-file-length ] ! priority ] ! processor ] ! processhandle ] ! error-detail ] ! name-option ] ! name:name-length ] ! process-descr:maxlen ] ! process-descr-len ] ! nowait-tag ] ! hometerm:home-term-length ] ! memory-pages ] ! jobid ] ! create-options ] !
swap-file:swap-file-length input:input STRING .EXT:ref:*, INT:value is not used, but you can provide it for informational purposes. If supplied, the swap file must be on the same system as the process being created. If the supplied name is in local form, the system where the process is created is assumed. Processes swap to a file that is managed by the Kernel-Managed Swap Facility (KMSF). For more information on this facility, see the Kernel-Managed Swap Facility (KMSF) Manual.
processhandle output INT .EXT:ref:10 returns the process handle of the new process. If you created the process in a nowait manner, the process handle is returned in the completion message sent to $RECEIVE rather than through this parameter. error-detail output INT .EXT:ref:1 returns additional information about some classes of errors. The sets of values for error-detail vary according to the error value, as described in Table 36 (page 1069).
If you created the process in a nowait manner, the process descriptor is returned in the completion message sent to $RECEIVE rather than in process-descr. process-descr-len output INT .EXT:ref:1 if process-descr is returned, contains its actual length in bytes. nowait-tag input INT(32):value if present and not -1D, indicates that the process is to be created in a nowait manner; the procedure returns as soon as process creation is initiated. For details, see Nowait Considerations (page 994).
create-options input INT:value provides information about the environment of the new process. The fields are: <9> <10> =0 If the caller is named, the process deletion message, if any, will go only to the current instance of the calling process. =1 If the caller is named, the process deletion message, if any, will go to whatever process has the calling process' name (regardless of sequence number) at that time.
debug-options input INT:value sets the debugging attributes for the new process. The fields are: Reserved (specify 0). <0:11> <12> <13> <14> <15> 1 Enter Debug or the Inspect debugger at the first executable instruction of the program's MAIN procedure. 0 Begin normal program execution. 1 If the process traps, create a saveabend file. 0 If the process traps, do not create a saveabend file.
• Library considerations A "user library" is an object file containing one or more procedures. Unlike a program, it contains no main procedure (no program entry point). Native user libraries can contain global instance data; TNS user libraries cannot. In a TNS process, unresolved symbols in the program are resolved first in the user library, if any, and then in the system library.
• Reserved process names The operating system reserved process name space includes these names: $Xname, $Yname, and $Zname, where name is from 1 through 4 alphanumeric characters. You must not use names of this form in any application. System-generated process names (from PROCESS_LAUNCH_, PROCESS_SPAWN_, PROCESS_CREATE_, NEWPROCESS[NOWAIT], PROCESSNAME_CREATE_, CREATEPROCESSNAME and CREATEREMOTENAME procedures) are selected from this set of names. For more information about reserved process names.
DEFINE Considerations • DEFINEs are propagated to the new process from the process context of the caller, from a caller-supplied buffer containing DEFINEs collected by calls to DEFINESAVE, or from both of these. DEFINEs are propagated to the new process according to the DEFINE mode of the new process and the propagation option specified in create-options. If both sets of DEFINEs are propagated and both sets contain a DEFINE with the same name, the DEFINE in the caller-supplied buffer is used.
• PROCESS_CREATE_ can create a new process separate from any batch job, even if the caller is a process that belongs to a batch job. In that case the job ID of the new process is 0. To start a new process that is not part of a batch job, specify 0 for jobid. • PROCESS_CREATE_ can create a new batch job and establish the new process as a member of the newly created batch job.
File privileges: • Only have impact when set on executables, user libraries, or ordinary DLLs. A process created from an executable file inherits the privileges of that executable file. • Are ignored when accessing files that are not in a restricted-access fileset. • Can be set by members of the Safeguard SPA group, using either the SETFILEPRIV command or the setfilepriv() function. Use the GETFILEPRIV command to get information about the file privileges for a file.
Related Programming Manuals For programming information about the PROCESS_CREATE_ procedure, see the Guardian Programmer's Guide. For programming information on batch processing, see the appropriate NetBatch manual.
PROCESS_DEBUG_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Related Programming Manual Summary The PROCESS_DEBUG_ procedure invokes the debugging facility on the calling process or on another process. The operating system provides a debugging facility that responds to debug events by passing control to one of two debugging utilities: Debug or Inspect. Debug is a low-level debugger.
terminal-name:length input:input STRING .EXT:ref:*, INT:value if supplied and if length is not 0, is a file name that designates the terminal from which the process is to be debugged. If used, the value of terminal-name must be exactly length bytes long. If terminal-name is partially qualified, it is resolved using the contents of the =_DEFAULTS DEFINE. The default is the current home terminal of the process to be debugged.
• • In addition to placing an explicit call to the PROCESS_DEBUG_ (or DEBUG) procedure in the source program, you can force a process into the debug state by: ◦ Starting the process using the TACL RUND (RUN DEBUG) command. The process enters the debug state before the first instruction of the MAIN procedure executes.
OSS Considerations When used on an OSS process, PROCESS_DEBUG_ forces the process into the Inspect debugger. You can change the home terminal by specifying terminal-name. Note that the home terminal is often the same device as the OSS controlling terminal. To debug an OSS process, one of these must be true: • The calling process must have the appropriate privileges; that is, it must be locally authenticated as the super ID on the system where the target process is executing.
PROCESS_DELAY_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Example Summary The PROCESS_DELAY_ procedure permits a process to suspend itself for a timed interval. The PROCESS_DELAY_ procedure is supported only in J-series and H-series RVUs.
difference can be noticeable. For a discussion about measuring long time intervals, see the SIGNALTIMEOUT procedure Considerations (page 1381).
PROCESS_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value General Considerations Mom Considerations Home Terminal Considerations I/O Processes That Control Multiple Devices OSS Considerations Examples Related Programming Manual Summary The PROCESS_GETINFO_ procedure obtains a limited set of information about a specified process.
• Some character-string parameters to PROCESS_GETINFO_ are followed by a parameter maxlen that specifies the maximum length in bytes of the character string and an additional parameter that returns the actual length of the string. Where these parameters are optional, the character-string parameter and the two parameters that follow it must either all be supplied or all be absent.
priority output INT .EXT:ref:1 returns the current execution priority of the specified process. The initial priority can be obtained by calling PROCESS_GETINFOLIST_. mom's-processhandle output INT .EXT:ref:10 returns the process handle of the mom of the specified process. hometerm:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns the fully qualified file name of the home terminal of the specified process.
program-file:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns the fully qualified Guardian program file name of the specified process. maxlen specifies the length in bytes of the string variable program-file. program-len output INT .EXT:ref:1 contains the actual length in bytes of the program file name being returned. swap-file:maxlen output:input STRING .EXT:ref:*, INT:value returns $volume.#0. Processes do not swap to $volume.
timeout input INT(32):value if present and not greater than zero, specifies how many hundredths of a second the process waits to get the process information; otherwise timeout defaults as follows: • for information about a process on the local node: none (wait forever) • for information about a process on a remote node: 60 second (see note) The maximum value is 2147483647. This parameter is supported on systems running H06.26 and later H-series RVUs and J06.
of the procedures superseded by PROCESS_GETINFO_, such as GETCRTPID and GETREMOTECRTPID, which treat a terminating process as if it did not exist. • Return value of PROCESS_GETINFO_ If the process specified in the call to PROCESS_GETINFO_ is in the starting or terminating stage, or if its program file or libraries are being loaded by RLD, then the procedure returns $< coldload-vol>.< coldload-subvol>.NOPROGRM as the program file name.
• If another process has become the mom of the specified process by a call to PROCESS_SETINFO_ or STEPMOM, then the process handle of that other process is returned in mom's-processhandle. • By default, an OSS process does not have a mom process; therefore, a null process handle is returned in mom's-processhandle.
PROCESS_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Auxiliary Data Iterative Attributes Loadfile Types Using the Loadfile Type Code Values Attribute Codes and Value Representations Considerations OSS Considerations Examples Related Programming Manual Summary The PROCESS_GETINFOLIST_ procedure obtains detailed information about a specified process or about a set of processes that meet specified criteria.
Syntax for C Programmers #include short PROCESS_GETINFOLIST_ ( [ short cpu ] ,[ short *pin ] ,[ char *nodename ] ,[ short length ] ,[ short *processhandle ] ,short *ret-attr-list ,short ret-attr-count ,short *ret-values-list ,short ret-values-maxlen ,short *ret-values-len ,[ short *error-detail ] ,[ short srch-option ] ,[ short *srch-attr-list ] ,[ short srch-attr-count ] ,[ short *srch-values-list ] ,[ short srch-values-len ] ,[ __int32_t oss-pid ] ,[ __int32_t timeout ] );
Parameters cpu input INT:value if present and not -1, is the number of the processor of interest. cpu must be used with pin. cpu,pin, and optionally nodename:length, must be specified either when a search is to be performed or when the caller is interested in a specific process but does not know its process handle.
and Value Representations (page 1019) for details on the attribute format. The attributes you can specify are described in Table 34 (page 1020). ret-attr-count input INT:value indicates the number of 16-bit words the caller is supplying in ret-attr-list. This number includes the attribute count and the word count for any auxiliary data supplied with auxiliary data attributes. Valid values for the ret-attr-count parameter are in the range 0 through 1024. ret-values-list output INT .
srch-option input INT:value has one of these values: 0 Return information for only the process specified by [nodename,] cpu,pin or by processhandle. You cannot specify oss-pid with this value. These parameters are ignored when srch-option is set to 0: srch-attr-list, srch-attr-count, srch-values-list, and srch-values-len. 1 Start a search at [nodename,] cpu,pin and return information for the first matching process. You cannot specify processhandle or oss-pid with this value.
srch-values-len input INT:value if present, is the length in words of srch-values-list. This parameter must be present if srch-option is 1 or 2. This parameter is ignored if srch-option is 0 or 3. oss-pid input INT(32):value if present and not null, contains the OSS process ID of the OSS process of interest. A null OSS process ID is obtained by calling the OSS_PID_NULL_ procedure. nodename:length must be specified when the caller wants information about an OSS process on a remote node.
5 Unable to communicate with cpu; cpu might not exist. 6 Unable to communicate with nodename. 7 No more matches exist; error-detail contains the number of processes for which information has been returned (might be 0). 8 (reserved) 9 Invalid search attribute code; error-detail contains the first code in question to be detected (error-detail is not an index into a list). 10 Invalid search value; error-detail contains the associated attribute code (not an index into a list).
ZSYSTAL section PROCESS^GETINFOLIST^RETURN with identifiers ZSYS^VAL^PINF^TYPE^suffix.
relative to the node on which the search is to be performed. For example, if a caller on node \A is inquiring about processes running on \B that have a home terminal of \A.$TERM1, the home terminal name in the search list must be \A.$TERM1 rather than $TERM1. File names that are in the returned values list are returned in fully qualified form. Brief descriptions of the attribute codes follow the table.
Table 34 PROCESS_GETINFOLIST_ Attribute Codes and Value Representations (continued) Code Attribute TAL Value Representation 37 licenses INT 38 PIN INT process file name INT bytelength, STRING 40 mom's process handle INT (10 words) 41 process file security INT 421 current priority INT 43 initial priority INT 44 remote creator INT 45 logged-on state INT 46 extended swap file INT bytelength, STRING 47 primary INT 481 process handle INT (10 words) 49 qualifier info availab
Table 34 PROCESS_GETINFOLIST_ Attribute Codes and Value Representations (continued) Code Attribute TAL Value Representation 77 maximum PFS size used INT(32) 80 effective group ID INT(32) 81 saved set-group-ID INT(32) 82 login name INT bytelength, STRING <= 32 chars 83 group list INT n, INT(32) [0:n-1] saved set-user-ID INT(32) 90 OSS process ID INT(32) 914 OSS parameter INT bytelength, STRING <= 1024 chars 924 OSS arguments INT bytelength, STRING <= 1024 chars 934 OSS program p
Table 34 PROCESS_GETINFOLIST_ Attribute Codes and Value Representations (continued) Code Attribute TAL Value Representation 119 process is TNS/R native INT 120 (reserved for privileged use) 1212(4<<12)5 program file and explicit library information variable-length structure 122 (4<<12) dynamically loaded library information variable-length structure 123 (reserved for future use) 1232(4<<12)5 implicit library variable-length structure 1242(4<<12)5 2 5 loadfile detail variable-length st
1 This attribute is also a parameter of PROCESS_GETINFO_ . 2 This attribute can be used as a search attribute. 3 This attribute cannot be specified as a return attribute 4 This attribute applies only to OSS processes. 5 This attribute requires auxiliary data. The data lengthn in the high-order 4 bits is shown as n<<12. 6 These attributes are identical to their 32-bit counterparts except that they contain 64-bit values rather than 32-bit values.
5 Debug breakpoint 6 Debug trap or signal 7 Debug request 8 Inspect memory-access breakpoint 9 Inspect breakpoint 10 Inspect trap or signal 11 Inspect request 12 saveabend 13 terminating 14 XIO initialization (not applicable on G-series RVUs) The OSS zombie process state has no Guardian equivalent. This attribute and the process state attribute (32) return the same information for bits <11:15>.
When used as a return attribute, lowered priority returns 0 if the process is not currently running with its priority lowered or if the target system is running an operating system version earlier than D10; it returns 1 if the process is currently running at reduced priority due to heavy processor use. • 15: process list as a query attribute, reports the list, if any, the process is on.
user. For logged-on processes, the effective user ID is equivalent to the process access ID (PAID). For other processes, the effective user ID is invalid and there is no PAID equivalent. The effective user ID determines access to OSS disk files, and the PAID determines access to Guardian disk files. • 26: OSS process ID of the OSS session leader (OSS processes only) as a search attribute, specifies the session leader. When used as a return attribute, this attribute returns the session leader.
<11> Wait on LINSP (Inspect event) <12> Wait on LCAN (message system: cancel) <13> Wait on LDONE (message system: done) <14> Wait on LTMF (TMF request) <15> Wait on LREQ (message system: request) The bits in the wait field are numbered from left to right. Thus, if octal 3 (%003) is returned, it means that bits 14 and 15 are equal to 1. • 32: process state returns the state of the process.
J-series TNS/E systems prior to T9050J01^AXI, a process is also deemed ready if it is running on the IPU where the information is collected (which can be in either the process calling PROCESS_GETINFOLIST_ or in the system monitor process). • 33: library file as a search attribute, specifies either a native user library file or a TNS user library file, and searches for the processes that are using it as a library.
<7:9> ID code allowed for write <10:12> ID code allowed for execute <13:15> ID code allowed for purge ID code can be one of these: • 0 Any user (local) 1 Member of owner's group (local) 2 Owner (local) 4 Any user (local or remote) 5 Member of owner's community (local or remote) 6 Owner (local or remote) 7 Super ID only (local) 42: current priority See the priority parameter returned by the PROCESS_GETINFO_ procedure. • 43: initial priority returns the initial execution priority.
• 53: creation timestamp returns the Julian timestamp that identifies the time when the process was created. If the target system is running an operating system version earlier than D10, 0F is returned. • 54: current pages returns the number of memory pages that have been swapped in by the process and are still resident.
• 64: stop request queue returns the status of a stop request on the queue. For more information on the stop request queue, see the PROCESS_STOP_ Procedure (page 1121). The return values are defined as follows: • 0 A stop request is not queued. 1 A stop request has not passed the security checks and the process is running at stop mode 1 or 2. The stop request is queued pending the reduction of the stop mode to 0.
• 73: applicable attributes returns the attribute types that are defined for the calling process. OSS attributes are 26, 27, and 90 through 99. Guardian extended attributes are 21 through 23, and 80 through 84. The return value of an undefined attribute is also undefined. The bits are defined as follows: <0:13> (reserved) <14> <15> • The process type, where: 0 Guardian process. Return values for OSS attributes are undefined. 1 OSS process. Return values for OSS attributes are defined.
• 92: OSS arguments (OSS processes only) returns the first 1024 bytes of the arguments of the parameter that created the process. Arguments in the returned string are separated by a space. A byte length of 0 is returned if the process is not an OSS process. • 93: OSS program pathname (OSS processes only) returns the fully qualified OSS program pathname of an OSS program. This OSS attribute is the OSS equivalent of the Guardian program file attribute (4).
• 102: origin of main stack returns the address of the origin of the main stack. NIL is returned if the target system is running an operating system version earlier than D40. If the value to be returned can be represented as a unique 32-bit address, the value will be returned as a 32-bit value. Otherwise, a value of 0xFFFC0000 (null address) will be returned. This attribute is superseded by attribute 142. The new attribute is identical except that an INT(64) data type is returned.
• 108: start of global data returns the address of the start of global data. NIL is returned if the target system is running an operating system version earlier than D40. If the value to be returned can be represented as a unique 32-bit address, the value will be returned as a 32-bit value. Otherwise, a value of 0xFFFC0000 (null address) will be returned. This attribute is superseded by attribute 148. The new attribute is identical except that an INT(64) data type is returned.
TAL Value Representation Description INT Length of file name. STRING File name. (The returned string is padded if necessary so that the next attribute returned will begin on an even-byte boundary. The padding is not counted in the reported file name length.) Similar information about SRLs is returned, in a different format, by attribute 121, which reports all the object files loaded in the process, not just SRLs. As a search attribute, this attribute finds processes that have loaded a particular SRL.
The loadfile information array contains these entries for each loadfile reported: TAL Value Representation Description INT(64) Address of text header INT(64) Creation volume sequence number of loadfile INT(32) Logical device number of loadfile INT(32) Loadfile type indicator (see Loadfile Types (page 1018)) Result value for TAL programs: For TAL programs, the result value is an instance of ZSYS^PINF^LOADFILE^INFO^DEF, in which the final member (Z^PARTIAL^INFO) is an array occurring the number of t
This information is returned: TAL Value Representation Description INT(64) Address of text header (combined text segment on native systems) INT(64) Creation volume sequence number of loadfile INT(32) Logical device number of loadfile INT(32) Loadfile type indicator (see Loadfile Types (page 1018)) INT(64) Address of text code segment (0 on native systems) INT(64) Address of data constant segment (0 on native systems) INT(64) Address of data variable segment (combined data segment on native sy
• 136: IPU affinity class This is a search attribute and specifies the IPU affinity class. When used as a return attribute, it returns the IPU affinity class of the process. The affinity class values are defined as follows: • 0 Unknown or None This is the initial state of a process when it is being created, and which will change to one of the following values by the time the process is fully created. 1 Hard Affinity The process is set on a specified IPU and cannot be moved.
This attribute supersedes attribute 106. This new attribute is identical except that an INT(64) data type is returned. 0 is returned if the target system is running an operating system version earlier than H06.24 or J06.13. • 147: maximum privileged stack size. returns the maximum privileged stack size in bytes. This attribute supersedes attribute 107. This new attribute is identical except that an INT(64) data type is returned.
• 156: number of 64-bit segments. returns the current number of 64-bit segments in the target process. 0 is returned if the target system is running an operating system version earlier than H06.24 or J06.13. • 158: absolute OSS program pathname (OSS processes only). returns the fully qualified absolute OSS program pathname (starting from “/”) of an OSS program. The returned pathname is the fully qualified pathname at the time of the process creation.
• All returned file names are fully qualified. • When using PROCESS_GETINFOLIST_ procedure, if you want to get information on every process in the processor, specify a search criteria that will find every process. For example, specify Search Attribute Code 9 with 0 as the search value. Information will be returned for all processes because all processes have a priority that is greater than or equal to 0.
attr^list := 8; ! get subdevice type only attr^count := 1; ret^vals^maxlen := 1; timeout = 6000 ! 1 minute timeout value error := PROCESS_GETINFOLIST_ ( , , , prochandle, attr^list, attr^count, ret^vals^list, ret^val^maxlen, ret^val^length, error^detail, , , , , , , timeout); Related Programming Manual For programming information about the PROCESS_GETINFOLIST_ procedure, see the Guardian Programmer's Guide.
PROCESS_GETPAIRINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The PROCESS_GETPAIRINFO_ procedure obtains basic information about a named process or process pair. You can specify the named process or process pair that you want information about in one of several ways: • Supply a process handle in the processhandle parameter. For a process pair, supply the process handle of either the primary or backup process.
Syntax for TAL Programmers error := PROCESS_GETPAIRINFO_ ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ • ! input/output error detail processhandle ] ! i 1 pair:maxlen ] ! i,o:i 2 pair-length ] ! o 3 primary-processhandle ] ! o 4 backup-processhandle ] ! o 5 search-index ] ! i,o 6 ancst-processhandle ] ! o 7 search-nodename:length ] ! i:i 8 options ] ! i 9 ancst:maxlen ] ! i,o:i 10 ancst-length ] ! o 11 error-detail ] ); ! o 12 The number in the comment after each parameter shows the value assigned to error-detail
the caller's node name, specify bit 14 of the options parameter. To search for a process on a remote node, fully qualify the process name. • If pair is the name of a named process that is not started, it cannot contain a sequence number. pair-length output INT .EXT:ref:1 if pair:maxlen is an output parameter, contains the length in bytes of the value returned in pair. primary-processhandle output INT .
options input INT:value specifies one or more options for the call as follows: Reserved (specify 0). <0:12> <13> <14> <15> 0 Return information only for running processes. 1 Also return information for named processes that are not started, but the process names are reserved. 0 Resolve a partially qualified process name in pair using the caller’s =_DEFAULTS DEFINE. 1 Resolve a partially qualified process name in pair using the caller’s node. 0 Return information only for named processes.
10 Unable to communicate with the node where the process resides. 11 Process is an I/O process, but the option to allow I/O processes was not selected. 13 Limited information is returned for a named process that is not started, but the process name is reserved. Considerations • To perform an indexed search, initialize search-index to 0D before issuing the first call. • Errors 11 and 12 are not returned during an indexed search. Excluded I/O processes are skipped over with no error reported.
PROCESS_LAUNCH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for param-list Structure Definitions for output-list Process Creation Error Codes General Considerations Nowait Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations File Privileges Considerations Related Programming Manuals Summary The PROCESS_LAUNCH_ procedure creates a new process and, optionally, assigns a number
Syntax for TAL Programmers ! input/output error detail error:= PROCESS_LAUNCH_ ( param-list ! i 1 ,[ error-detail ] ! o 2 ,[ output-list:maxlen ] ! o:i 3 ,[ output-list-len ] ); ! o 4 • The number in the comment after each parameter shows the value assigned to error-detail when identifying an error on that parameter. Parameters param-list input INT .
Returned Value INT Outcome of the call. Table 35 (page 1061) summarizes possible values for error. Structure Definitions for param-list The param-list parameter specifies the attributes of the new process.
Field Name Default Value Z^SWAPFILE^NAME %HFFFC0000%D Z^SWAPFILE^NAME^LEN 0D Z^EXTSWAPFILE^NAME %HFFFC0000%D Z^EXTSWAPFILE^NAME^LEN 0D Z^PROCESS^NAME %HFFFC0000%D Z^PROCESS^NAME^LEN 0D Z^HOMETERM^NAME %HFFFC0000%D Z^HOMETERM^NAME^LEN 0D Z^DEFINES^NAME %HFFFC0000%D Z^DEFINES^NAME^LEN 0D Z^NOWAIT^TAG -1D Z^PFS^SIZE 0D Z^MAINSTACK^MAX 0D Z^HEAP^MAX 0D Z^SPACE^GUARANTEE 0D Z^CREATE^OPTIONS 0D Z^NAME^OPTIONS 0 Z^DEBUG^OPTIONS %100000 Z^PRIORITY -1 Z^CPU -1 Z^MEMORY^PAGES
Note that in the C zsysc file, the type zsys_ddl_char_extaddr_def is defined as long. The type char_far* is the equivalent to the type zsys_ddl_char_extaddr_def in DLAUNCHH. Therefore, do not use the structure definition from zsysc and the default structure value from DLAUNCHH at the same time. C programs must initialize the P_L_DEFAULT_PARMS_ define in the $SYSTEM.SYSTEM.DLAUNCHH header file.
Z^LENGTH is one of: • the length of the ZSYS^DDL^PLAUNCH^PARMS structure (if version 1 is specified for Z^VERSION). • the length of the ZSYS^DDL^PLAUNCH^PARMS64 structure (if version 2 is specified for Z^VERSION). • the length of the struct process_launch_parms_ structure (if DLAUNCHH is used rather than zsysc) Because the structure is subject to change, Z^LENGTH is used by PROCESS_LAUNCH_ to further identify the version of the structure.
For TNS processes, if specified and if Z^EXTSWAPFILE^NAME^LEN is not 0, this parameter specifies the address of a string containing the name of a file to be used as the swap file for the default extended data segment of the process. If used, the string must be exactly Z^EXTSWAPFILE^NAME^LEN bytes long. If the swap file name is partially qualified, it is resolved using the =_DEFAULTS DEFINE. The swap file must be on the same node as the process being created and must be an unstructured file.
Z^PFS^SIZE if nonzero, specifies the size in bytes of the process file segment (PFS) of the new process. The value is no longer meaningful; it is ignored. PFS size is 8 MB in G-series RVUs and 32 MB in H-series and J-series RVUs. Z^MAINSTACK^MAX specifies the maximum size, in bytes, of the process main stack. The specified size cannot exceed 32 megabytes (MB).
Name (ZSYS^VAL^ ) Value Description PCREATOPT^DEFINELIST 8 Propagate DEFINEs in Z^DEFINES only. Otherwise, propagate only the DEFINEs in the caller's context. PCREATOPT^DEFOVERRIDE 4 Enable DEFINEs if PCREATOPT^DEFENABLED is specified. Disable DEFINEs if PCREATOPT^DEFENABLED is not specified. Otherwise, use caller's DEFINE mode. PCREATOPT^FRCLOWOVER 32 Ignore the value of the caller's inherited force-low PIN attribute. Otherwise, use the value of the caller's inherited force-low PIN attribute.
Valid values for Z^DEBUG^OPTIONS are as follows: Name (ZSYS^VAL^) Value Description PCREATOPT^DBGOVERRIDE 2 Use the debugger and saveabend options specified regardless of program-file flag settings. Otherwise, use the program-file flag settings. Debugger and saveabend options are specified by PCREATOPT^SAVABEND and PCREATOPT^RUND described in this table.
Structure Definitions for output-list The output-list parameter provides information on the outcome of the PROCESS_LAUNCH_ procedure call. The structure returned is the same structure used in the nowait PROCESS_LAUNCH_ and PROCESS_CREATE_ completion message.
Z^TAG If it contains the value of -1D, indicates a waited request. Other values indicate the value specified in the ZSYS^DDL^PLAUNCH^PARMS.Z^NOWAIT^TAG or ZSYS^DDL^PLAUNCH^PARMS64.Z^NOWAIT^TAG of the param-list parameter. If ZSYS^DDL^PLAUNCH^PARMS was used to create this process the Z^TAG field will contain the NOWAIT flag and a 64-bit sign-extended copy will be placed by the system in the Z^TAG64 field (described below).
Table 35 Summary of Process Creation Errors (continued) error Description 2 Parameter error; from PROCESS_LAUNCH_ and PROCESS_SPAWN_, error-detail contains the literal for the first parameter to be found in error. See Table 36 (page 1069) for possible values. From PROCESS_CREATE_, error-detail contains the number of first parameter found to be in error, where 1 designates the leftmost parameter.
Table 35 Summary of Process Creation Errors (continued) error Description On a TNS/E system, unresolved procedure references in a TNS program are bound to an illegal label, so an attempt to invoke an unresolved procedure generates an Illegal Instruction trap at the call site. The default handling is process termination, but if the process has armed a trap handler, that handler will be invoked. (Note that there are no non-PIC programs on a TNS/E system; all native programs are PIC.
Table 35 Summary of Process Creation Errors (continued) error Description 32 Unable to lock the main stack of a native IOP. (This error is returned only to privileged callers.) 33 Security inheritance failure. 35 Internal process creation error; error-detail is an internal code that localizes the error. 36 Child's PFS error; error-detail contains a file-system error number.1 37 Unable to allocate global data for the process.
Table 35 Summary of Process Creation Errors (continued) error Description 53 The specified version, Z^VERSION, of the ZSYS^DDL^PLAUNCH^PARMS structure is incompatible with the specified length, Z^LENGTH,of the structure (PROCESS_LAUNCH_ only). 54 An error occurred at an internal process creation interface. 55 The specified space guarantee, Z^SPACE^GUARANTEE (PROCESS_LAUNCH_) or Z^SPACEGUARANTEE (PROCESS_SPAWN_), cannot be allocated. 56 Internal error.
Table 35 Summary of Process Creation Errors (continued) error Description 69 A file-system error was encountered in the run-time loader (rld) library; error-detail contains the file-system error number. 70 Invalid file format in the runtime loader (rld) library; error-detail subcodes are described in Table 37 (page 1070).
Table 35 Summary of Process Creation Errors (continued) error 78 Description 12 A process that has a licensed, but unprivileged program attempted to load an unlicensed non-public DLL. 13 A licensed or privileged loadfile has globalized symbols. 14 The loadfile was specified as dataResident and is not licensed, has no callable functions, and is not a program that has a priv entry point. 15 This process can only be run by the local super ID.
Table 35 Summary of Process Creation Errors (continued) error Description 82 A DEFINE is recognized by the systems, but it is not a valid DEFINE. Error details are: 0 The define is not class SEARCH. 2055 An attribute other than CLASS or SUBVOL0 is specified. All other details are as reported by the DEFININFO function. 83 A file-system error occurred on the TNS Emulator while attempting process creation. error-detail contains a file-system error number.
Table 35 Summary of Process Creation Errors (continued) error Description 113 The timeout value in the ZSYS^DDL^FDINFO.Z^TIMEOUT field of the fdinfo parameter was reached before the file descriptors specified in the fdinfo parameter could be opened. It is also possible that one of the file descriptors is not responding (PROCESS_SPAWN_ only). 114 A process cannot be created because privileged OSS processes are not supported (PROCESS_SPAWN_ only, before the G05 RVU.).
Table 36 error-detail Codes for PROCESS_LAUNCH_and PROCESS_SPAWN_ Errors 2 and 3 (continued) error-detail PROCESS_LAUNCH_ Structure or Parameter in Error PROCESS_SPAWN_ Structure or Parameter in Error 18 Z^DEFINES^NAME Z^DEFINES 19 Z^DEBUG^OPTIONS Z^DEBUGOPTIONS 20 Z^PFS^SIZE Z^PFSSIZE 22 param-list not returned by PROCESS_SPAWN_ 23 error-detail Z^TPCDETAIL 24 output-list not returned by PROCESS_SPAWN_ 25 output-list-len not returned by PROCESS_SPAWN_ 50 not returned by PROCESS_LAUN
Table 37 error-detail Codes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (continued) error-detail Description 10 The file resident size is greater than the code area length. 11 The file was not prepared by the nld utility or the Binder program. 12 The file has undefined data blocks. 13 The file has data blocks with unresolved references. 14 The file has too many TNS code segments. 15 Accelerated code length in the file is invalid. 16 Accelerated code address in the file is invalid.
Table 37 error-detail Codes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (continued) error-detail Description 45 The file being started can run only in the Guardian environment and it is being started in the OSS environment, or vice versa. 46 Either the TNS program or the TNS user library (but not both) expected the library to contain global data.
Table 37 error-detail Codes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (continued) error-detail Description 73 The p_flags in the ELF header for the resident text header are not as expected; the file may be corrupt. 74 The loadfile has resident text, but no data constant segment, and is not marked data_resident. This combination is not supported. 75 The DLL has callable functions but also has unprotected data. This is not supported.
For more information about building TNS user libraries, see the Binder Manual. For more information about building non-PIC TNS/R SRLs, see the nld Manual and the noft Manual. For more information about building PIC TNS/R DLLs, see the ld Manual. For more information about building PIC TNS/E DLLs, see the eld Manual and the enoft Manual. For more information about loading PIC programs and DLLs, see the rld Manual.
ID of the new process is the same as the user ID of the program file's owner and the new process is always local. • I/O error to the home terminal An I/O error to the home terminal can occur if there are undefined externals in the program file and PROCESS_LAUNCH_ is unable to open or write to the home terminal to display the undefined externals messages. The error-detail parameter contains the file-system error number that resulted from the open or write that failed.
Batch Processing Considerations NOTE: The job ancestor facility is intended for use by the NetBatch product. Other applications that use this facility might be incompatible with the NetBatch product. • When the process being created is part of a batch job, PROCESS_LAUNCH_ sends a job process creation message to the job ancestor of the batch job. (See the discussion of job ancestor in the Guardian Programmer's Guide.
• ◦ Login name ◦ Current working directory (cwd) ◦ Maximum file size ◦ No other OSS process attribute is inherited by the new process. OSS file opens in the calling process are not propagated to the new process. File Privileges Considerations On systems running J06.11 or later J-series RVUs or H06.22 or later H-series RVUs, files have an additional file privilege attribute that specifies special privileges, if any, a file has when accessing files in a restricted-access fileset.
files in restricted-access filesets. It is not required that the executable file be in the restricted-access fileset. If the executable file has a file privilege, then any user library or ordinary DLL loaded by the process must also have that file privilege. Otherwise, an error is reported when the process attempts to load that library or DLL. The PRIVSETID file privilege can be inherited by child processes created using fork()because the parent and child process share the same executable.
PROCESS_MONITOR_CPUS_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Messages Example Summary The PROCESS_MONITOR_CPUS_ procedure instructs the operating system to notify the application process if a designated processor module either: • Fails (indicated by the absence of an operating system "I'm alive" message) • Returns from a failed to an operable state (that is, reloaded by means of a command interpreter RELOAD command) The calling application process is notified by
Messages • processor down System message -2 (processor down) is received if failure occurs with a processor module that is being monitored (for the description and form of system messages, see the Guardian Procedure Errors and Messages Manual). NOTE: Be aware that this message expires in 3 minutes; it must be read before expiration or it will be lost. • processor up System message -3 (processor up) is received if a reload occurs with a processor module that is being monitored.
PROCESS_MONITOR_NET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The PROCESS_MONITOR_NET_ procedure enables or disables receipt of system messages concerning the status of processors in remote systems.
PROCESS_MONITOR_NEW_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The PROCESS_MONITOR_NEW_ procedure enables or disables receipt of the SETTIME and Power On messages.
PROCESS_MONITOR_VCORE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Summary The PROCESS_MONITOR_VCORE_ procedure enables or disables the receipt of a system message associated with the enabling of Core License. It also indicates a change in the number of enabled IPUs or CPUs.
PROCESS_SETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value set-attr-code Attribute Codes and Value Representations Considerations 32-bit/64-bit Considerations Safeguard Considerations OSS Considerations Example Related Programming Manual Summary The PROCESS_SETINFO_ procedure alters a single nonstring attribute of a specified process and optionally returns the prior value of the attribute.
Syntax for C Programmers #include short PROCESS_SETINFO_ ( [ short *processhandle ] ,[ short specifier ] ,short set-attr-code ,[ short *set-value ] ,[ short set-value-len ] ,[ short *old-value ] ,[ short old-value-maxlen ] ,[ short *old-value-len ] ); Syntax for TAL Programmers error := PROCESS_SETINFO_ ( [ processhandle ] ,[ specifier ] ,set-attr-code ,[ set-value ] ,[ set-value-len ] ,[ old-value ] ,[ old-value-maxlen ] ,[ old-value-len ] ); ! ! ! ! ! ! ! ! i i i i i o i o
Considerations (page 1089) for this procedure, and the PROCESS_CREATE_ procedure General Considerations (page 992). set-value input INT .EXT:ref:* specifies the new value of the attribute to be altered. For more information about process attributes, see set-attr-code Attribute Codes and Value Representations, the Considerations (page 1089) for this procedure, and the PROCESS_CREATE_ procedure General Considerations (page 992). set-value-len input INT:value specifies the length in words of set-value.
set-attr-code Attribute Codes and Value Representations The individual set-attr-code attribute codes and their associated value representations are: Code Attribute TAL Value Representation 40 mom's process handle INT (10 words) 41 * process file security INT 42 priority INT 45 *+ logged-on state INT 47 * primary INT 49 * qualifier information available INT 50 * + Safeguard-authenticated logon INT 69 *+ stop on logoff INT 70 *+ propagate logon INT 71 *+ propagate stop-on-logoff
• 42: current priority sets execution priority to be assigned to the new process. Execution priority is a value in the range of 1 to 199, where 199 is the highest possible priority. • 45: logged-on state sets information about the logged-on state of the process. The fields are: Reserved (specify 0). <0:14> <15> • 0 Process is not logged on. 1 Process is logged on. 47: primary causes the current process to become the primary process if it is the backup process of a process pair.
the current main stack size, call the PROCESS_GETINFOLIST_ procedure with the current main stack size attribute (103). • 144: maximum size of the main stack identical to attribute 104, except that it is specified with INT(64).
If PROCESS_SETINFO_ is used to set the mom of an OSS process, the new mom receives the Guardian process deletion message when the OSS process terminates. The received message contains an indication that the terminated process was an OSS process and also contains the OSS process ID; otherwise, the message is the same as one received for a terminating Guardian process. For more information on the Guardian parent of an OSS process, see Keeping Track of OSS Child Processes (page 1116).
set^attribute^code , new^priority , set^value^length ); Related Programming Manual For programming information about the PROCESS_SETINFO_ procedure, see the Guardian Programmer's Guide.
PROCESS_SETSTRINGINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The PROCESS_SETSTRINGINFO_ procedure alters a single string-form attribute of a specified process, and optionally returns the prior value of the attribute. You can use the PROCESS_SETINFO_ procedure to alter nonstring process attributes.
PROCESS_SETSTRINGINFO_ also treats a process handle with -1 in the first word as a null process handle. specifier input INT:value indicates whether the operation affects both members of a named process pair. Valid values are: 0 Act upon the specified process only. 1 Act upon both members of current instance of named process pair if processhandle specifies a member of a named process pair. The default is 0. A change to the home terminal affects only a single process (specifier is treated as 0).
Considerations • The caller of PROCESS_SETSTRINGINFO_ must be the super ID, the group manager of the process access ID, or a process with the same process access ID as the process or process pair whose attribute is being changed. For information about the process access ID, see the PROCESS_GETINFO_ procedure General Considerations (page 1009) and the Guardian User's Guide. The caller must be local to the same system as the specified process.
PROCESS_SPAWN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for fdinfo Structure Definitions for inheritance Structure Definitions for process-extension Structure Definitions for process-results Nowait Considerations 64-bit Considerations Considerations for Resolving File Names Considerations for Resolving External References Considerations for Reserved Names Keeping Track of OSS Child Processes Creator Access ID and Process Access ID
caller. When it is created in a nowait manner, its identification is returned in a system message sent to the caller's $RECEIVE file. • You can obtain a level of fault tolerance in OSS processes by calling PROCESS_SPAWN_ to create OSS processes from a monitor implemented as a Guardian process pair. The monitor checks that the created OSS process continues to run and restarts it if there is a failure. For more information on writing fault-tolerant programs, see the Guardian Programmer's Guide.
Syntax for C Programmers #include __int32_t PROCESS_SPAWN_ ( char _ptr32 *oss-program-file ,[ void _ptr32 *fdinfo ] ,[ char _ptr32 *argv ] ,[ char _ptr32 *envp ] ,[ void _ptr32 *inheritance ] ,[ __int32_t inheritance-length ] ,[ void _ptr32 *process-extension ] ,[ void _ptr32 *process-results ] ,[ __int32_t nowait-tag ] ,[ char _ptr32 *path ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defi
fdinfo input STRING .EXT:ref:(ZSYS^DDL^FDINFO) specifies the file creation mask, current working directory, and file descriptors to be opened or duplicated by the new process. This parameter also allows the caller to limit the time allowed for the child process to open all of its files. If the pathnames are absolute pathnames, they are resolved relative to the child's root. If the pathnames are relative pathnames, they are resolved relative to the child's current working directory.
process-extension input The process-extension parameter may be either: STRING .EXT:ref:(ZSYS^DDL^PROCESSEXTENSION^DEF) or STRING .EXT:ref:(ZSYS^DDL^PROCESSEXTENSION64^DEF) which specifies the Guardian attributes of the new process. For information on how to set the field values of the structure, see Structure Definitions for process-extension (page 1105). Either data type may be passed as the process-extension parameter.
Specifically, if the path parameter is not specified or is null (0D), and a shell script does not have the syntax shown above, PROCESS_SPAWN_ returns OSS errno value 4008 (ENOEXEC) in the ZSYS-DDL-PROCESSRESULTS.Z-ERRNO field of the process-results parameter. NOTE: Use only the files specified in these pages to obtain the definitions for the structures and literals. The definitions in other files may produce undesired results. Returned Value INT(32) .EXT:ref:1 The OSS process ID of the new process.
In the C tdmext.
Z^UMASK is the OSS file mode creation mask of the new process. A value of -1 indicates that the OSS file mode creation mask of the calling process is used. For more information see the umask() function reference page either online or in the Open System Services System Calls Reference Manual. Z^CWD is the address of a string containing the null-terminated OSS pathname of the OSS current working directory of the new process.
One of these file access flags must be supplied: Name (ZSYS^VAL^ ) Value Description Corresponding open() Flag OSSOPEN^RDONLY 0 Open only for reading O_RDONLY OSSOPEN^RDWR 2 Open for reading and writing O_RDWR OSSOPEN^WRONLY 1 Open only for writing O_WRONLY One of these file status flags can be supplied: Name (ZSYS^VAL^ ) Value Description Corresponding open() Flag OSSOPEN^APPEND 4 Open only for append access O_APPEND OSSOPEN^CREAT 8 Create and open the file O_CREAT OSSOPEN^EXCL
In the C spawnh file, the structure for the inheritance parameter is defined as: typedef struct inheritance { short flags; #define SPAWN_SETGROUP 0x01 #define SPAWN_SETSIGMASK 0x02 #define SPAWN_SETSIGDEF 0x04 #define SPAWN_NOTDEFD 0xFFF8 char filler_1[2]; pid_t pgroup; sigset_t sigmask; sigset_t sigdefault; } inheritance /* /* /* /* not used by PROCESS_SPAWN_ controls child sigmask controls child sigmask undefined bit fields */ */ */ */ C programs must initialize the inheritance structure by setting th
Structure Definitions for process-extension The process-extension parameter specifies the Guardian attributes of the new process.
Field Name Default Value Z^HEAPMAX 0D Z^SPACEGUARANTEE 0D When passing the type ZSYS^DDL^PROCESSEXTENSION64^DEF, the structure for the process-extension parameter is defined in the TAL ZSYSTAL file as: STRUCT ZSYS^DDL^PROCESSEXTENSION64^DEF (*); BEGIN INT(16) Z^VER; INT(16) Z^LEN; INT(32) Z^PFSSIZE; FIXED Z^MAINSTACKMAX; FIXED Z^HEAPMAX; FIXED Z^SPACEGUARANTEE; FIXED Z^LIBRARYNAME; FIXED Z^SWAPFILENAME; FIXED Z^EXTSWAPFILENAME; FIXED Z^PROCESSNAME; FIXED Z^HOMETERM; FIXED Z^DEFINES; INT Z^DEFINESLEN;
Field Name Default Value Z^NAMEOPTIONS ZSYS^VAL^PCREATOPT^NONAME Z^CREATEOPTIONS ZSYS^VAL^PCREATOPT^DEFAULT Z^DEBUGOPTIONS ZSYS^VAL^PCREATOPT^DEFAULT Z^OSSOPTIONS ZSYS^VAL^PSPAWNOPT^DEFAULT In the C tdmext.
Z^VER is the version of the ZSYS^DDL^PROCESSEXTENSION64 structure. Because the structure is subject to change, Z^VER is used by PROCESS_SPAWN_ to identify the version of the structure. NOTE: This field is not in the ZSYS^DDL^PROCESSEXTENSION structure. Z^LEN is the length of the ZSYS^DDL^PROCESSEXTENSION or ZSYS^DDL^PROCESSEXTENSION64 structure. Because the structure is subject to change, Z^LEN is used by PROCESS_SPAWN_ to identify the version of the structure.
For native processes, this parameter is ignored because TNS/R native processes do not need an extended swap file. The default value is 0D, or 0F if using ZSYS^DDL^PROCESSEXTENSION64. For more information about the swap files, see Considerations for Resolving File Names (page 1116) and the PROCESS_LAUNCH_ procedure DEFINE Considerations (page 1075). Z^PRIORITY is the initial execution priority to be assigned to the new process.
Z^HOMETERM can be a terminal device or a named or unnamed user process. The default value of 0D indicates the home terminal of the caller. The default value of 0D, or 0F if using ZSYS^DDL^PROCESSEXTENSION64, indicates the home terminal of the caller. Z^MEMORYPAGES For TNS processes,specifies the minimum number of memory pages allocated to the new process for user data. The actual amount of memory allocated is processor-dependent.
For more information on DEFINEs, see the PROCESS_LAUNCH_ procedure DEFINE Considerations (page 1075). Z^DEFINES is the address of a null-terminated string that specifies a set of DEFINEs to be propagated to the new process. The default value is 0D, or 0F if using ZSYS^DDL^PROCESSEXTENSION64. The set of DEFINEs must have been created through one or more calls to the DEFINESAVE procedure. DEFINEs are propagated according to the values specified in Z^CREATEOPTIONS.
Z^OSSOPTIONS specifies the OSS options. The valid value for Z^OSSOPTIONS is as follows: Name (ZSYS^VAL^ ) PSPAWNOPT^OSSDEFAULT Value 0 Description The default value is the only value available. Z^MAINSTACKMAX specifies the maximum size, in bytes, of the process main stack. The specified size cannot exceed 32 MB. The default value of 0D, or 0F if using ZSYS^DDL^PROCESSEXTENSION64, indicates that the main stack can grow to 1 MB in the TNS/R environment and to 2 MB in the TNS/E environment.
Structure Definitions for process-results The process-results parameter provides Guardian information on the outcome of the PROCESS_SPAWN_ procedure call.
C programs must initialize the process_extension_results structure by using the #define DEFAULT_PROCESS_EXTENSION_RESULTS in the tdmext.h header file. Z^LEN is the length of the ZSYS^DDL^PROCESSRESULTS structure. Because the structure is subject to change, Z^LEN is used by PROCESS_SPAWN_ to identify the version of the structure. Z^PHANDLE returns the process handle of the new process.
Z^TPCERROR indicates the outcome of the Guardian process creation. This parameter is the same as the error parameter reported by PROCESS_LAUNCH_. For details, see Table 35 (page 1061) and Table 36 (page 1069). See also the PROCESS_CREATE_ procedure Nowait Considerations (page 1115). Z^TPCDETAIL returns additional information about some classes of Guardian errors. This parameter is the same as the error-detail parameter reported by PROCESS_LAUNCH_.
Considerations for Resolving File Names • All file names are specified using OSS pathname syntax and are resolved using the caller's OSS current working directory. • Resolving the problem of spawning remote shell scripts ◦ Use PROCESS_SPAWN_ to spawn a remote shell and pass the name of the script as one of its arguments. The shell will run the script. ◦ Spawn a local shell and use the Expand file system to read the remote shell script.
4. • 5. The caller process calls PROCESS_GETINFOLIST_ with the OSS process ID of the child process and obtains the new process handle of the OSS process indicating that it still exists. The caller process receives the process deletion message with a -12 completion code (indicating that the child process has migrated to a new process handle by calling one of the OSS tdm_exec set of functions). A child process migrates from a processor that is running to a processor that fails: 1.
Buffer space for DEFINEs being propagated to a new process is limited to 2 MB whether the process is local or remote. However, the caller can propagate only as many DEFINEs as the child's PFS can accommodate in the buffer space for the DEFINEs themselves and in the operational buffer space needed to do the propagation. The maximum number of DEFINEs that can be propagated varies depending upon the size of the DEFINEs being passed.
• • When the Z^JOBID field of the process-extension parameter is set to -1: ◦ If the caller is not part of a batch job, then neither is the newly created process; its job ID is 0. ◦ If the caller is part of a batch job, then the newly created process is part of the same job because its job ID is propagated to the new process. Once a process belongs to a batch job, it remains part of the job.
PRIVSETID File Privilege The PRIVSETID file privilege allows the locally-authenticated super ID to start a process from an executable and use a privileged switch operation, such as setgid() or setuid(), to switch to another user ID or group ID (without a password) and, based on the permissions for that ID, access files in restricted-access filesets. It is not required that the executable file be in the restricted-access fileset.
PROCESS_STOP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations NetBatch Considerations Safeguard Considerations OSS Considerations Examples Related Programming Manual Summary The PROCESS_STOP_ procedure deletes a process or process pair. When this procedure is used to delete a Guardian process or an OSS process, a process deletion system message is sent to the mom of the process and to any other process that is entitled to receive the message.
Parameters processhandle input INT .EXT:ref:10 specifies the process handle of the process to be stopped. If this parameter is omitted or null, the caller is stopped. The null process handle is one which has -1 in each word. (For details, see the PROCESSHANDLE_NULLIT_ Procedure (page 1140).) However, PROCESS_STOP_ also treats a process handle with -1 in the first word as a null process handle. specifier input INT:value for a named process pair, indicates whether both members are to be stopped.
completion-code input INT:value is the completion code to be returned in the process deletion system message and, for a terminating OSS process, in the OSS process termination status. Specify this parameter only if the calling process is terminating itself and you want to return a completion code value other than the default value of 0 (STOP) or 5 (ABEND). A nonprivileged caller cannot pass a negative value for completion-code. For a list of completion codes, see Appendix C: Completion Codes.
Considerations • When PROCESS_STOP_ executes, all open files associated with the deleted process are closed. If a process had BREAK enabled, BREAK is disabled.
◦ ◦ If the process is a remote process running on the local system and the request to stop it is from a local process, these user IDs or associated processes can stop the process: – local super ID – the process' creator access ID (CAID) or the group manager of the CAID – the process' process access ID (PAID) or the group manager of the PAID If the process is a remote process on the local system and the request to stop it is from a remote process, these user IDs or associated processes can stop the p
a file that the process had open with exclusive access or before you try to create a new process with the same name. The best way to be sure that a process has terminated is to wait for the process deletion message. • Stopping a process that has the Inspect or saveabend attribute set If the process being stopped has either the Inspect attribute or the saveabend attribute set, and if DMON exists, PROCESS_STOP_ returns error 0 but deletion of the process is delayed until DMON approves it.
reference page either online or in the Open System Services System Calls Reference Manual for details on the OSS process termination status. In addition, a process deletion system message is sent to the MOM, GMOM, or ancestor process according to the usual Guardian rules. The OSS process ID of the terminated process is included in the process deletion message. • • When the PROCESS_STOP_ procedure is used to stop an OSS process other than the caller, the process handle must be specified in the call.
PROCESS_SUSPEND_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Safeguard Considerations OSS Considerations Example Related Programming Manual Summary The PROCESS_SUSPEND_ procedure places a process or process pair into the suspended state, preventing that process from being active (that is, from executing instructions). A process can also be suspended by a call to the SUSPENDPROCESS procedure, or by a TACL SUSPEND command.
Returned Value INT A file-system error code that indicates the outcome of the call: 0 Process successfully suspended. 2 Process is already in the suspended state. 11 Process does not exist. 48 Security violation. 201 Unable to communicate with processor where the process is running. Considerations • Reactivating a process You can reactivate a suspended process or process pair by calling PROCESS_ACTIVATE_.
Example error := PROCESS_SUSPEND_ ( proc^handle ); Related Programming Manual For programming information about the PROCESS_SUSPEND_ procedure, see the Guardian Programmer's Guide.
PROCESSACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PROCESSACCESSID procedure is used to obtain the process access ID (PAID) of the calling process.
PROCESSFILESECURITY Procedure (Superseded by PROCESS_SETINFO_ Procedure or PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PROCESSFILESECURITY procedure is used to examine or set the file security for the current process.
If security is omitted, PROCESSFILESECURITY returns the current security information in old-security without changing it. Returned Value INT The old file security.
PROCESSHANDLE_COMPARE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The PROCESSHANDLE_COMPARE_ procedure compares two process handles and reports whether they are identical, represent different processes of the same process pair, or different. PROCESSHANDLE_COMPARE_ is primarily useful for determining whether processes form a process pair.
Considerations • PROCESSHANDLE_COMPARE_ considers two process handles to belong to the same process pair if they contain the same sequence number. • PROCESSHANDLE_COMPARE_ compares only the contents of the input parameters; it does not send any messages. • If either of the parameter supplied to PROCESSHANDLE_COMPARE_ is missing, the process terminates with instruction failure (trap 01).
PROCESSHANDLE_DECOMPOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The PROCESSHANDLE_DECOMPOSE_ procedure returns one or more parts of a process handle.
cpu output INT .EXT:ref:1 if present, returns the processor number of the process designated by processhandle. pin output INT .EXT:ref:1 if present, returns the process identification number of the process designated by processhandle. nodenumber output INT(32) .EXT:ref:1 if present, returns the number of the node in which the process designated by processhandle resides. nodename:maxlen output:input STRING .
Considerations If you specify procname or procname-length, and processhandle designates a named process, PROCESSHANDLE_DECOMPOSE_ looks up the process by name. If it does not exist, error 14 is returned. Related Programming Manual For programming information about the PROCESSHANDLE_DECOMPOSE_ procedure, see the Guardian Programmer's Guide.
PROCESSHANDLE_GETMINE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Related Programming Manual Summary The PROCESSHANDLE_GETMINE_ procedure obtains the caller's process handle. For a caller that needs to obtain only its own process handle, a call to PROCESSHANDLE_GETMINE_ is more efficient than a call to PROCESS_GETINFO_. For general information about process handles, see Appendix D: File Names and Process Identifiers.
PROCESSHANDLE_NULLIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Summary The PROCESSHANDLE_NULLIT_ procedure initializes a process handle to a null value. A process handle that has -1 in each word is recognized by the operating system as being null. For further information about process handles, see Appendix D: File Names and Process Identifiers.
PROCESSHANDLE_TO_CRTPID_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The PROCESSHANDLE_TO_CRTPID_ procedure converts a process handle to the corresponding process ID (CRTPID). For a description of process IDs, see Appendix D: File Names and Process Identifiers.
pair-flag input INT:value specifies whether process-id designates a process pair (1 it does; 0 it does not). If pair-flag is set and the process is named, the cpu and pin values in process-id are set to -1 instead of the cpu and pin of the process. The default is 0. node-number input INT(32):value if present and not -1D, identifies the node with respect to which process-id is normalized. If this parameter is omitted or -1D, the caller's node is used. See the process-id parameter.
PROCESSHANDLE_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The PROCESSHANDLE_TO_FILENAME_ procedure converts a process handle to a process file name.
filename-length output INT .EXT:ref:1 is the actual length of the value returned in filename. If an error other than 18 (unknown system) is returned, 0 is returned for this parameter. options input INT:value specifies options. The fields are: <0:14> Not currently used (specify 0) <15> For named processes: if set, specifies that the sequence number not be included in filename for a named process. If this bit is not set, the sequence number is included.
PROCESSHANDLE_TO_STRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The PROCESSHANDLE_TO_STRING_ procedure converts a process handle to the equivalent process string. See Considerations (page 1146), for a description of process strings.
process-string-length output INT .EXT:ref is the actual length of the value returned in process-string. If an error occurs, 0 is returned. nodename:length input:input STRING .EXT:ref:*, INT:value if supplied and if length is not 0, specifies the node name to be included in process-string. If used, the value of nodename must be exactly length bytes long. If nodename designates the same node as indicated in processhandle, no node name is included in process-string.
PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PROCESSINFO procedure is used to obtain process status information.
process-id input, output INT:ref:4 is an array where PROCESSINFO returns the four-word process ID of the process whose status is actually being returned. This can be different from the process whose status is requested through cpu,pin (see the error parameter). On input, the process-id contents can be used as a search criterion (see the search-mode parameter). Note that process ID is a four-word array where: [0:2] [3] Process name or creation timestamp .<0:3> Reserved .
home-terminal input, output INT:ref:12 is an array where PROCESSINFO returns the internal-format device name of the process-id's home terminal. On input, the home-terminal contents can be used as a search criterion (see the search-mode parameter). sysnum input INT:value specifies the system (in a network) where the process for which information is to be returned is running. If this parameter is omitted, the local system is assumed.
process-time output FIXED:ref:1 returns the process time, in microseconds, for which the process has executed. wait-state output INT:ref:1 returns the wait field indicating what, if anything, the process is waiting on. It is obtained from the wait field of the awake/wait word in the process' process control block.
7 Debug request 8 Inspect memory access breakpoint 9 Inspect breakpoint 10 Inspect trap or signal 11 Inspect request 12 saveabend 13 terminating 14 XIO initialization library-filename output INT:ref:12 returns the internal-format file name of the library file used by the process. If the process does not have an associated library file, then library-filename is blank-filled. swap-filename output INT:ref:12 returns $volume.#0. Processes do not swap to $volume.
Returned Value INT Outcome of the call: 0 Status for process cpu,pin is returned. 1 Process cpu,pin does not exist or does not match specified criteria (see search-mode). Status for next higher cpu,pin in the specified processor is returned. The four-word process ID of the process for which status is being returned is returned, in the process-id parameter (if present).
PROCESSNAME_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The PROCESSNAME_CREATE_ procedure returns a unique process name that is suitable for passing to the PROCESS_LAUNCH_, PROCESS_CREATE_, or PROCESS_SPAWN_ procedure. This type of naming (as opposed to using a predefined process name) is used when the name of a process pair does not need to be known to other processes in the system or network.
name-type input INT:value specifies the type of name desired. Values are: 0 4–character name 1 5–character name If this parameter is omitted, 0 is used. The local portion of a 4-character name is as described in the CREATEPROCESSNAME procedure. The local portion of a 5-character name is of the form $X0nnnor $X1nnn, where nnn represents 1 to 3 alphanumeric characters except e, i, o, and u. This set of names is part of the set of process names that are reserved by the operating system.
Example INT type := 1; ! return a 5-character name INT form := 1; ! return name in local form . . . err := PROCESSNAME_CREATE_ ( name:max^length, actual^length, type, , form ); IF err THEN ... Related Programming Manual For programming information about the PROCESSNAME_CREATE_ procedure, see the Guardian Programmer's Guide.
PROCESSOR_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Processor Attribute Codes and Value Representations Processor Types and Models Considerations Example Summary The PROCESSOR_GETINFOLIST_ procedure obtains configuration information and statistics about a processor. The processor of interest is specified by node name and processor number. The information about a processor is organized as a set of attributes.
Parameters nodename:length input:input STRING .EXT:ref:*, INT:value if present and if length is not 0, specifies the name of the node that contains the processor of interest. nodename must be exactly length bytes long. If nodename:length is omitted or if length is 0, the name of the local node is used. cpu input INT:value if present and if not -1, is the number of the processor of interest. If cpu is omitted, then the caller's processor number is used. In that case, nodename:length must be omitted.
Returned Value INT Outcome of the call: 0 Information is returned for the specified process. 1 File-system error; error-detail contains the error number. Error 563 is returned if the ret-values-list buffer is too small to contain all of the requested information. 2 Parameter error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left.
Table 38 PROCESSOR_GETINFOLIST_ Attribute Codes and Value Representations (continued) Code Attribute TAL Value Representation 16 memory queue length INT 17 system coldload time FIXED 18 elapsed time FIXED 19 busy time FIXED 20 idle time FIXED 21 interrupt time FIXED 22 processor queue length INT 23 dispatches unsigned INT(32) 24 PCBs in low PINs INT number of elements, INT ARRAY 25 PCBs in high PINs INT number of elements, INT ARRAY 26 time list elements INT number of elem
Table 38 PROCESSOR_GETINFOLIST_ Attribute Codes and Value Representations (continued) Code Attribute TAL Value Representation 57 memory-management attributes INT(32) 58 segments in use INT(32) 59 maximum segments used INT(32) 60 updates part of the release ID (the two digits that follow the period) INT 61 internal use only 62 availability of IEEE floating point on the current system INT 65 64-bit dispatch count unsigned INT(64) 72 system name INT bytelength, STRING 74 number of ena
• 4: page size the page size of physical memory, in bytes. • 5: memory size the size of physical memory, in pages. If the number of pages exceeds 2,147,483,647 (2**31 - 1), the returned value is -1D. • 6: first virtual page the page number of the first swappable page. • 7: swappable pages the current number of memory pages that can be swapped. If the number of pages exceeds 2,147,483,647 (2**31 - 1), the returned value is -1D. • 8: free pages the current number of nonallocated memory pages.
• 18: elapsed time the amount of time, in microseconds, since the processor was loaded. • 19: busy time the amount of time, in microseconds, that processes have been executing since the processor was loaded. The comparison of busy time values returned by this attribute across a Core License change of the number of enabled IPUs does not provide useful results. Attribute 74 can be used to determine if the number of enabled IPUs has changed at the comparison interval.
• 28: breakpoints the number of processor breakpoints currently set. • 29: send busy the amount of time, in microseconds, that has been spent performing message sends since the processor was loaded. • 35: interrupt count an array of counters for the various interrupts.
• 38: processor queue state an array of two integers and a FIXED. The first integer is the maximum number of processes ready to run at any time since the Measure product started collecting statistics on the processor. The second integer is the current number of processes ready to run. The FIXED contains the total number of microseconds that all processes have spent on the ready queue. • 39: memory queue state an array of two integers and a FIXED.
• 50: accelerated time the number of microseconds the processor spent in accelerated code since the Measure product started collecting statistics on the processor. If the Measure product is not collecting statistics on the processor or if the processor of interest is running a RVU earlier than D20, -1F is returned. If the processor of interest is not a native processor, then 0F is returned. • 51: clock resolution the resolution of the system clock in nanoseconds.
• 62: availability of IEEE floating point on the current system this attribute can be identified as CPUINFO_ATTR_FP_IEEE_VER, and can have these values: • 0 No IEEE floating point. 1 First version of IEEE floating-point support. >1 Reserved for future versions of IEEE floating-point support. 65: 64-bit dispatch count the number of dispatch interrupts since the processor was loaded in a 64-bit counter. • 72: system name the system name. See Table 39 (page 1168) for system name STRING values.
external representations differ. Positive or negative values indicate the clock is being sped up or slowed down, respectively. • 87: time when rate adjusted the time, in microseconds since cold load, since the system clock rate was modified by a call to SYSTEMCLOCK_SET_ or SETSYSTEMCLOCK. • 88: time when time set the time, in microseconds since cold load, since the system time was set by a call to SYSTEMCLOCK_SET_ or SETSYSTEMCLOCK.
NOTE: Attribute codes 94–97 are available only on systems running H06.27, J06.16, and subsequent RVUs. • 94: CPU busy time the time, in microseconds, that processes have been executing since the processor was loaded. • 95: IPU busy time an array of the amount of time, in microseconds, that processes have been executing in each enabled IPU since the processor was loaded. The number of array elements is the number of enabled IPUs (see attribute 74).
Table 39 Summary of Processor Types and Models (continued) Type (Code 2) Model Value (Code 47) Model Name Name (Code 48) Full Name (Code 49) System Name (Code 72) 6 0 0 NSR-L HP NonStop System RISC Model L CPU1 NonStop CO-Cyclone/R 6 0 0 NSR-L HP NonStop System RISC Model L CPU1 NonStop Cyclone/R 6 0 0 NSR-L HP NonStop System RISC Model L CPU1 NonStop K120 6 0 0 NSR-L HP NonStop System RISC Model L CPU1 NonStop K1000 6 0 0 NSR-L HP NonStop System RISC Model L CPU1 NonStop K
Table 39 Summary of Processor Types and Models (continued) Type (Code 2) Model Value (Code 47) Model Name Name (Code 48) Full Name (Code 49) System Name (Code 72) 9 14(E) NSR-J NSR-J HP NonStop System RISC Model J CPU NonStop S7800 10 1 NSE-A NSE-A HP NonStop System EPIC Model A CPU NS16000 10 2 NSE-D NSE-D HP NonStop System EPIC Model D CPU NS14000 10 11 NSE-B NSE-B HP NonStop System EPIC Model B CPU NS1000 10 12 NSE-C NSE-C HP NonStop System EPIC Model C CPU NEOVIEW 10
1 This system is no longer supported. Considerations • If PROCESSOR_GETINFOLIST_ returns a nonzero error value, the contents of ret-values-list and ret-values-len are undefined. Example In this example, the processor type and model of the caller's processor are returned in a structure. LITERAL type = 2; LITERAL model = 47; INT attributes [0:1] := [ type, model ]; STRUCT processor^info; BEGIN INT processor^type; INT processor^model; END; . . .
PROCESSOR_GETNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The PROCESSOR_GETNAME_ procedure returns a processor's type and model. You can designate the processor of interest either by supplying a processor number with a node number or name, or by supplying a processor number alone. Alternatively, you can supply just the numeric representation of the processor type.
Parameters cpu-number input INT:value is the number that identifies the processor of interest. This parameter is required when either node-name or node-number is specified. If cpu-number is omitted or equal to -1, and if neither node-name nor node-number is specified, then the caller's processor is used. name:maxlen output:input STRING .EXT:ref:*, INT:value returns the processor type as a character string. maxlen specifies the length in bytes of the string variable name and must be at least 3 bytes.
cpu-type-out output INT .EXT:ref:1 returns the processor type in numeric form. The possible values are shown earlier under the description of the name parameter (see the column labeled "Processor Type"). These are the same values that are returned by the PROCESSORTYPE procedure. node-name:length input:input STRING .EXT:ref:*, INT:value if present and if length is not equal to 0, specifies the name of the node where the processor of interest is located.
Returned Value INT A file-system error code that indicates the outcome of the call: 0 Information returned successfully. 22 Parameter or buffer out of bounds. 29 Missing parameter. 201 Unable to communicate over this path. 590 Parameter value bad or inconsistent.
PROCESSORSTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Summary The PROCESSORSTATUS procedure returns the highest processor number plus 1 of the configured processor modules in a system and the operational states of all the processor modules. For further information about supported processors, See Table 39 (page 1168).
For each bit: 1 up indicates that the corresponding processor module is up (operational) 0 down indicates that the corresponding processor module is down or does not exist PROCESSORSTATUS Procedure 1177
PROCESSORTYPE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The PROCESSORTYPE procedure returns the processor type of a specified system and processor. For further information about supported processors, see Table 39 (page 1168).
Example TYPE^CPU := PROCESSORTYPE ( PROCESSOR , SYSTEM^NUM ); PROCESSORTYPE Procedure 1179
PROCESSSTRING_SCAN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The PROCESSSTRING_SCAN_ procedure scans an input string for a process string and returns the corresponding process handle or a single component of the process string converted to internal form. Device names are optionally accepted in the input string. See Considerations (page 1182) for the definition of process string.
the process string, the current default value in the =_DEFAULTS DEFINE is used for determining the process handle. length-used output INT .EXT:ref:1 if present, returns the number of characters in string that are part of the process string. If error 13 is returned, length-used is the number of characters that were accepted as valid before the name was determined to be invalid. processhandle output INT .EXT:ref:10 if present, returns the process handle of the designated process.
pin output INT .EXT:ref:1 if present, returns the PIN value contained in the process string when stringtype is 2; otherwise -1 is returned. options input INT:value specifies desired options. The fields are: <15> <0:14> 0 Error 13 occurs if options <15> = 0 and the input string name exceeds 6 characters including the ‘$' character. 1 Causes an input string exceeding 6 characters to be accepted without error. Reserved (specify 0). When options is omitted, 0 is used.
PROCESSTIME Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PROCESSTIME procedure returns the process execution time of any process in the network.
Considerations You cannot use PROCESSTIME for a high-PIN process except when omitting cpu,pin. This is because a high-PIN cannot fit into cpu,pin. Example IF ( PROCESS^TIME := PROCESSTIME ( CPU^PIN , SYS^NUM )) >= 0F THEN ... ! successful. ELSE ... ! PROCESSTIME not available.
PROGRAMFILENAME Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PROGRAMFILENAME procedure is used to obtain the name of the calling process' program file.
PURGE Procedure (Superseded by FILE_PURGE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations Safeguard Considerations OSS Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The PURGE procedure is used to delete a disk file that is not open.
Condition Code Settings < (CCL ) indicates that the PURGE failed (call FILEINFO or FILE_GETINFO_). Note, however, that in the case of a disk free-space error (such as file-system errors 52, 54, 58), the file is purged, and an error returns. =(CCE) indicates that the file purged successfully. > (CCG) indicates that the device is not a disk.
PUTPOOL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manual Summary The PUTPOOL procedure returns a block of memory to a buffer pool initialized by the DEFINEPOOL procedure.
Considerations GETPOOL and PUTPOOL do not check pool data structures on each call. A process that destroys data structures can fail on a call to GETPOOL or PUTPOOL: a Guardian TNS process can get an instruction failure trap (trap 1) or an invalid address reference trap (trap 0); an OSS or native process can receive a SIGILL or SIGSEGV signal.
13 Guardian Procedure Calls (R) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter R. Table 40 lists all the procedures in this section.
RAISE_ Procedure Summary Considerations Summary NOTE: The RAISE procedure can be called only from native processes. The RAISE_ procedure is the pTAL procedure name for the C raise() function. The C raise() function complies with the POSIX.1 standard. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
READ[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Errors for READ[X] Errors for READX Only Example Related Programming Manuals Summary The READ[X] procedures return data from an open file to the application process' data area. The READ procedure is intended for use with 16-bit addresses, while the READX procedure is intended for use with 32-bit extended addresses.
• CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int. • The function value returned by READ[X], which indicates the condition code, can be interpreted by _status_lt(), _status_eq(), or _status_gt() (defined in the file tal.h).
tag input INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this READ[X]. NOTE: The system stores the tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed. If READX is used, the user must call the AWAITIOX procedure to complete the I/O.
suspended and queued in the "locking" queue behind other processes attempting to lock or read the file or record. NOTE: A deadlock condition occurs if a call to READ[X] is made by a process having multiple opens on the same file and the filenum used to lock the file differs from the filenum supplied to READ[X].
• Queue files READ[X] can be used to perform a nondestructive read of a queue file record. If KEYPOSITION[X] is used to position to the beginning of the file, the first READ[X] performed returns a record with a length of 8 bytes and contents of all zeroes. Subsequent READ[X] calls will return data from records written to the file. • Performing concurrent large no-wait I/O operations on NSAA systems In H06.28/J06.
• Structured files ◦ A subset of records for sequential READ[X]s The subset of records read by a series of calls to READ[X] is specified through the POSITION or KEYPOSITION procedures. ◦ Reading of an approximate subset of records If an approximate subset is being read, the first record returned is the one whose key field, as indicated by the current key-specifier, contains a value equal to or greater than the current key.
The READ[X] procedure reads records sequentially on the basis of a beginning relative byte address (RBA) and the length of the records read. ◦ Odd unstructured If the unstructured file is created with the odd unstructured attribute (also known as ODDUNSTR) set, the number of bytes read is exactly the number of bytes specified with read-count. If the odd unstructured attribute is not set when the file is created, the value of read-count is rounded up to an even number before the READ[X] is executed.
Related Programming Manuals For programming information about the READ procedure, see the Guardian Programmer's Guide, the Enscribe Programmer's Guide, and the data communication manuals.
READ^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The READ^FILE procedure is used to read a file sequentially. The file must be open with read or read/write access. READ^FILE is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
count-returned output INT:ref:1 returns the number of bytes returned to buffer. If I/O is nowait, this parameter has no meaning and can be omitted. The count is then obtained in the call to WAIT^FILE. prompt-count input INT:value is a count of the number of bytes in buffer, starting with element zero, to be used as an interactive prompt for terminals or interprocess files. If omitted, the interactive prompt character defined in OPEN^FILE is used.
Related Programming Manual For programming information about the READ^FILE procedure, see the Guardian Programmer's Guide.
READEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The READEDIT procedure reads one line from a specified EDIT file and returns it to the caller in unpacked format. READEDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
record-number input, output INT(32):ref:1 if present, specifies the record number of the line to be read. If record-number: • is greater than or equal to 0, READEDIT reads the line (if any) with the smallest EDIT line number that is greater than or equal to the value of 1000 times record-number. • is -1, READEDIT reads the lowest-numbered line (if any) in the file. • is -2, READEDIT reads the highest-numbered line (if any) in the file.
Returned Value INT A file-system error code that indicates the outcome of the call. Example error := READEDIT (filenumber, record^num, line^image, line^maxlength, line^actual^length, , space^fill); IF error THEN ... ! handle error IF line^actual^length < 0 THEN ... ! buffer (line^image) ! too small for return ! value Related Programming Manual For programming information about the READEDIT procedure, see the Guardian Programmer's Guide.
READEDITP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The READEDITP procedure reads one line from a specified EDIT file and returns it to the caller in EDIT packed line format. READEDITP is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
record-number returns the value of the file's new current record number after the read has been performed. This is equal to the record number of the line that was read, or it is -2 (end of file) if no line was read. packed-line output STRING .EXT:ref:* is a string array that contains the line in unpacked format that is the outcome of the operation. The length of the unpacked line is returned in the packed-length parameter.
READLOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Considerations for READLOCKX Only Errors for READLOCKX Only Related Programming Manuals Summary The READLOCK[X] procedures sequentially lock and read records in a disk file, exactly like the combination of LOCKREC and READ[X].
Syntax for TAL Programmers CALL READLOCK[X] ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters filenum input INT:value is the number of an open file that identifies the file to be read. buffer output INT:ref:* (for READLOCK) STRING .EXT:ref:* (for READLOCKX) is an array in the application process where the information read from the file returns. read-count input INT:value is the number of bytes to be read: {0:4096}.
to FILE_GETINFO_ or FILEINFO shows that an error 551 occurred; this error is advisory only and does not indicate an unsuccessful read operation. = (CCE) indicates that the READLOCK[X] is successful. > (CCG) indicates end of file (EOF). There are no more records in this subset. Considerations • Nowait I/O and READLOCK[X] If the READLOCK[X] procedure is used to initiate an operation with a file-opened nowait, it must complete with a corresponding call to the AWAITIO[X] procedure.
4. 5. 6. Define memory pools for the allocated extended data segments. Use the POOL_GETSPACE_PAGE_ procedure to obtain a block of memory, which will be used as the read or write buffer. When the no-wait I/O operation is complete, use the POOL_PUTSPACE_ procedure to return the memory to the pools. On non-NSAA systems, reads and writes larger than 4KB on key-sequenced files may be performed directly from or into the application’s buffer. • See also the READ[X] procedure Considerations (page 1194).
Related Programming Manuals For programming information about the READLOCK procedure, see the Enscribe Programmer's Guide.
READUPDATE[X|XL] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Considerations Disk File Considerations Interprocess Communication Considerations Considerations for READUPDATEX and READUPDATEXL Errors for READUPDATEX and READUPDATEXL Related Programming Manuals Summary The READUPDATE[X|XL] procedures read data from a disk or process file in anticipation of a subsequent write to the file.
Syntax for C Programmers #include _cc_status READUPDATE ( short filenum ,short _near *buffer ,unsigned short read-count ,[ unsigned short _near *count-read ] ,[ __int32_t tag ] ); #include _cc_status READUPDATEX ( short filenum ,char _far *buffer ,unsigned short read-count ,[ unsigned short _far *count-read ] ,[ __int32_t tag ] ); #include short READUPDATEXL ( short filenum ,char _far *buffer ,__int32_t read-count ,[ __int32_t _far *c
Parameters filenum input INT:value is the number of an open file that identifies the file to be read. buffer output INT:ref:* (for READUPDATE) STRING .EXT:ref:* (for READUPDATEX and READUPDATEXL) is an array where the information read from the file returns.
Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO with filenum of 0). < (CCL) is also returned following a successful read with an insertion-ordered alternate key path if the alternate key value of the current record is equal to the alternate key value in this record along that path. A call to FILE_GETINFO_ or FILEINFO shows that an error 551 occurred; this error is advisory only and does not indicate an unsuccessful read operation.
• Default locking mode action If the default locking mode is in effect when a call to READUPDATE[X|XL] is made to a locked file or record, but the filenum of the locked file differs from the filenum in the call, the caller of READUPDATE[X|XL] is suspended and queued in the "locking" queue behind other processes attempting to access the file or record.
Disk File Considerations • Large data transfers For READUPDATEX only, large data transfers (more than 4096 bytes), can be enabled by using SETMODE function 141. See Table 44 (page 1319). • Record does not exist If the position specified for the READUPDATE[X|XL] operation does not exist, the call is rejected with error 11. (The positioning is specified by the exact value of the current key and current-key specifier.
Interprocess Communication Considerations • Replying to messages Each message read in a call to READUPDATE[X|XL], including system messages, must be replied to in a corresponding call to the REPLY[X|XL] procedure. • Queuing several messages before replying Several interprocess messages can be read and queued by the application process before a reply must be made.
process file segment (PFS—also known as system buffers) for I/O transfers. A file opened by OPEN uses a PFS buffer for I/O transfers, except for large transfers to DP2 disks. • If the extended address of the buffer is odd, bounds checking rounds the address to the next lower word boundary and checks an extra byte as well. The odd address is used for the transfer.
READUPDATELOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Considerations for READUPDATELOCKX Only OSS Considerations Errors for READUPDATELOCKX Only Example Related Programming Manuals Summary The READUPDATELOCK[X] procedures are used for random processing of records in a disk file.
#include _cc_status READUPDATELOCKX ( short filenum ,char _far *buffer ,unsigned short read-count ,[ unsigned short _far *count-read ] ,[ __int32_t tag ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int.
tag input INT(32): value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this READUPDATELOCK[X]. NOTE: The system stores the tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed. If READUPDATELOCKX is used, you must call AWAITIOX to complete the I/O.
On NSAA systems, data being read or written may be stored in the 32MB process file segment (PFS) along with the open file information. This segment provides an upper limit on the number of concurrent no-wait I/O operations with large read-count or write-count values for those applications with a large number of open files. You can work around this limitation by following these guidelines in your application: 1. Define read and write buffers with sizes that are multiples of 16 KB. 2.
Errors for READUPDATELOCKX Only In addition to the errors returned from READUPDATELOCK, error 22 is returned from READUPDATELOCKX when: • The address of a parameter is extended, but either the extended data segment is invalid or the address is for a selectable segment that is not in use at the time of the call. • The address of a parameter is extended, but it is an absolute address and the caller is not privileged.
RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO[L]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development.
Parameters process-id output INT:ref:4 returns the four-word process ID of the process that sent the last message read through the $RECEIVE file. If the process is of the named form, and thus is in the destination control table (DCT), the information returned consists of: [0:2] [3] $process-name .<0:3> Reserved .<4:7> Processor number where the process is executing .
filenum output INT:ref:1 returns the file number of the file in the requesting process associated with this message. If the received message is a system message that is not associated with a specific file open, this parameter contains -1. read-count output INT:ref:1 returns the number of bytes requested in reply to the message. If the message is the result of a request made in a call to WRITE[X], read-count will be 0.
• Remote opener with a long process file name If the calling process used FILE_OPEN_ to open $RECEIVE and did not request to receive C-series format messages, and if the last message read from $RECEIVE is from a remote process that has a process name consisting of more than five characters, then the value of process-id returned by RECEIVEINFO is undefined. • Sync ID definition A sync ID is a double-word, unsigned integer. Each process file that is open has its own sync ID.
REFPARAM_BOUNDSCHECK[64]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The REFPARAM_BOUNDSCHECK[64]_ procedures check the validity of parameter addresses passed to the procedure that calls it. Bounds checking performed by the system is enough for most applications. This procedure, however, provides additional checks for those few applications that might need it.
return -1; return 0; } A function with no parameters cannot use _frame_edge(), nor can a C++ function whose first parameter is a reference (that is, not a value or a pointer). Syntax for TAL Programmers error := REFPARAM_BOUNDSCHECK[64]_ ( start-address ,area-length ,framestart ,flags ); ! ! ! ! i i i i Parameters start-address input STRING .EXT:ref:* (for REFPARAM_BOUNDSCHECK_) STRING .EXT64:ref:* (for REFPARAM_BOUNDSCHECK64_) identifies the start of the data area to be bounds checked.
is possible only for procedures running on the default stack of the process; it is not performed if framestart designates an address on a user thread stack. In pTAL, the correct value to pass in framestart is obtained using the $PARAMSTART function. In TAL, you use the $XADR function. A set of DEFINEs are available to mask the differences between pTAL and TAL. See Considerations for details. flags input INT:value specifies options. The bits indicate: must be zero.
this area can be the TNS data stack, the main stack, an unprivileged selectable extended data segment, or any of the code areas mapped into KUSEG. ◦ For CALLABLE procedures running on the TNS data stack, no part of the reference parameter can be within an area that starts at the base of the CALLABLE procedure's stack and extends to 0 locations beyond the L register of the CALLABLE procedure.
REFRESH Procedure (Superseded by DISK_REFRESH_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. On G-series RVUs, the function provided by both the REFRESH and DISK_REFRESH_ procedures is no longer needed. The REFRESH procedure is used to write control information to the associated disk volume.
volname can be either: $volname or \sysnumvolname If omitted, all FCBs for all volumes are written to their respective disks. Returned Value INT A file-system error code that indicates the outcome of the call. (For a list of all file-system errors, see the Guardian Procedure Errors and Messages Manual.) Considerations • When REFRESH is called without a volname, the error return is always 0.
REMOTEPROCESSORSTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Summary The REMOTEPROCESSORSTATUS procedure supplies the status of processor modules in a particular system in a network.
Considerations • Where to find the system number The system number for a particular system whose name is known can be obtained from the LOCATESYSTEM procedure. • Equivalencing the two words of status The two words of status can be separated by the usual technique of equivalencing INT variables to the high- and low-order words.
REMOTETOSVERSION Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The REMOTETOSVERSION procedure identifies which version of the operating system is running on a remote system.
Example In the following example, if the operating-system version is D10, the returned value contains "N" in bits <0:7> and binary 10 in bits <8:15>. REMOTE^VERSION := REMOTETOSVERSION ( SYSTEM^NUM ); Related Programming Manual For programming information about the REMOTETOSVERSION procedure, see the Guardian Programmer's Guide.
RENAME Procedure (Superseded by FILE_RENAME_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Safeguard Considerations OSS Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The RENAME procedure is used to change the name of a disk file that is open. If the file is temporary, assigning a name causes the file to be made permanent.
Considerations • Purge access for RENAME The caller must have purge access to the file for the RENAME to be successful. Otherwise, the RENAME is rejected with file-system error 48 (security violation). • Volume specification for new-name The volume specified in new-name must be the same as the volume specified when opening the file. Neither the volume name nor the system name can be changed by RENAME.
REPLY[X|XL] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Considerations Considerations for REPLYX and REPLYXL Errors for REPLYX and REPLYXL Example Related Programming Manual Summary The REPLY[X|XL] procedures are used to send a reply message to a message received earlier in a corresponding call to READUPDATE[X|XL] on the $RECEIVE file.
#include short REPLYXL ( [ ,[ ,[ ,[ ,[ • const char _far *buffer ] __int32_t write-count ] __int32_t _far *count-written ] short message-tag ] short error-return ] ); The function value returned by REPLY[X], which indicates the condition code, can be interpreted by _status_lt(), _status_eq(), or _status_gt() (defined in the file tal.h).
message-tag input INT:value is the message-tag returned from FILE_GETRECEIVEINFOL_ (or FILE_GETRECEIVEINFO_ or LASTRECEIVE or RECEIVEINFO) that associates this reply with a message previously received. This parameter can be omitted if message queuing is not performed by the application process (that is, FILE_OPEN_ or OPEN procedure receive-depth = 1).
If $RECEIVE is opened with receive-depth = 0, only READ[X] can be called; READUPDATE[X|XL] and REPLY[X] fail with error 2 ("operation not allowed on this type of file"). • Using the message-tag If more than one message is queued by the application process (that is, receive-depth> 1), a message tag associated with each incoming message must be obtained in a call to the FILE_GETRECEIVEINFOL_ (or FILE_GETRECEIVEINFO_ or LASTRECEIVE or RECEIVEINFO) procedure immediately following each call to READUPDATE[X|XL].
REPOSITION Procedure (Superseded by FILE_RESTOREPOSITION_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary The REPOSITION procedure is used to position a disk file to a saved position (the positioning information having been saved by a call to the SAVEPOSITION procedure). The REPOSITION procedure passes the positioning block obtained by SAVEPOSITION back to the file system.
Considerations • The REPOSITION procedure cannot be used with files that are larger than approximately 2 gigabytes, including both Enscribe format 2 and OSS files. If an attempt is made to use the REPOSITION procedure with these files, error 581 is returned. For information on how to perform the equivalent task with files larger than approximately 2 gigabytes, see the FILE_RESTOREPOSITION_ Procedure (page 502).
RESETSYNC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations Example Summary The RESETSYNC procedure is used by the backup process of a process pair after a failure of the primary process. With this procedure, a different series of operations might be performed from those performed by the primary before its failure.
Considerations • File number has not been opened If the RESETSYNC file number does not match the file number of the open file that you are trying to access, the call to RESETSYNC is rejected with file-system error 16. • Not receiving messages If filenum designates a process, and if the $RECEIVE file of that process is not opened with receipt of RESETSYNC messages enabled, then the RESETSYNC procedure fails with file-system error 7.
RESIZEPOOL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Related Programming Manual Summary The RESIZEPOOL procedure changes the size of a pool that was initialized by the DEFINEPOOL procedure.
Returned Value INT A file-system error code that indicates the outcome of the call: 0 Successful call; the size of the specified pool had been changed to new-pool-size. 12 The call would shrink the pool too much, leaving less area than that reserved by GETPOOL; the reserved blocks must be returned by a PUTPOOL. 21 An invalid new-pool-size was specified. 22 One of the parameters specifies an address that is out of bounds. 29 A required parameter was not supplied.
RESIZESEGMENT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Considerations for Privileged Callers Example Related Programming Manual Summary The RESIZESEGMENT procedure alters the size of an existing data segment (for example, a segment created by SEGMENT_ALLOCATE_). NOTE: The RESIZESEGMENT procedure perform the same operation as the SEGMENT_RESIZE64_ Procedure (page 1295), which is recommended for new code.
For a flat segment, the value must be in the range 1 byte through the maximum size defined by the max-size parameter of the SEGMENT_ALLOCATE_ procedure. For a selectable segment, the value must be in the range 1 byte through 127.5 megabytes (133,693,440 bytes). Returned Value INT A file-system error code that indicates the outcome of the call: -2 Unable to allocate page table space (not returned for unaliased segments). -1 Unable to allocate segment space.
Type of segment At segment allocate At memory access At segment resize size. Shrinking: the number of pages reserved is reduced (subject to change). KMSF-backed extensible segment. One page is reserved (subject to change). Additional pages are reserved. Growing: no additional pages are reserved. Shrinking: the number of pages reserved is reduced if the new size is less than the highest address of accessed memory (subject to change).
14 Guardian Procedure Calls (S) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter S. Table 41 lists all the procedures in this section.
Table 41 Procedures Beginning With the Letter S (continued) SIGISMEMBER_ Procedure SIGJMP_MASKSET_ Procedure SIGLONGJMP_ Procedure SIGNAL_ Procedure SIGNALPROCESSTIMEOUT Procedure SIGNALTIMEOUT Procedure SIGPENDING_ Procedure SIGPROCMASK_ Procedure SIGSETJMP_ Procedure SIGSUSPEND_ Procedure SSIDTOTEXT Procedure STACK_ALLOCATE_ Procedure STACK_DEALLOCATE_ Procedure STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure) STOP Procedure (Superseded by PROCESS_STOP_ Procedure) STRING_UPSHIFT_ Procedure SUS
SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary The SAVEPOSITION procedure is used to save a disk file's current file positioning information in anticipation of a need to return to that position. The positioning information is returned to the file system in a call to the REPOSITION procedure when you want to return to the saved position.
For key-sequenced files where positioning is performed by: • Primary key, the count is calculated by 7 + (primary-keylen + 1) / 2 • An alternate key, the count is calculated by 7 + (max-alternate-keylen + primary-keylen + 1) / 2 For unstructured files and for entry-sequenced and relative files where no alternate keys exist, the count is 4.
SEGMENT_ALLOCATE[64]_ Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary The SEGMENT_ALLOCATE[64]_ procedures allocate data segments for use by the calling process. These procedures can allocate read/write segments, read-only segments, and extensible segments. SEGMENT_ALLOCATE_ allocates segments only in 32-bit address space; SEGMENT_ALLOCATE64_ also allocates segments in 64-bit address space.
• SEGMENT_ALLOCATE_ is declared in CEXTDECS; SEGMENT_ALLOCATE64_ is declared in kmem.h and CEXTDECS. • Header file kmem.h defines constants for parameter and error values for SEGMENT_... procedures.
limit larger than the flat address space. In native processes, the program globals and the heap are allocated at the low-address end of the 32-bit flat-segment range, and the heap grows upward; by default the system allocates other segments downward from the high-address end. In addition to data segments allocated by SEGMENT_ALLOCATE[64]_, the 32-bit flat segment area can also hold text and data segments for DLLs as well as shared-memory segments attached by the OSS shmat() function. • ◦ For H06.24, J06.
If a segment is being shared by the PIN method (see pin), this rule applies to the sharers: • The segment-size parameter must be omitted, and the size of the segment is the same as that from the initial SEGMENT_ALLOCATE[64]_ call. If a segment is being shared by the file name method (see segment-type), these rules apply to the sharers: • If the swap file supplied in the filename parameter does not exist at the time of the call, the segment-size parameter must be supplied.
Performance is increased by using KMSF. However, if you want to save the data in the segment after the process terminates, specify a permanent swap file name. KMSF swap files have the clear-on-purge attribute, which provides a level of security for swapped data. For more information on KMSF, see the Kernel-Managed Swap Facility (KMSF) Manual.
pin input INT:value if present and not equal to -1, pin is specified and requests allocation of a segment that is shared by the PIN method. The pin value is the process identification number (PIN) of the process that has previously allocated the segment and with which the caller wants to share the segment. The process designated by pin must be in the same processor as the caller. Processes sharing a segment by this method must reference the segment by the same segment-id.
SEGMENT_TYPE_EXTENS (1) If pin is not specified, create an extensible segment; if filename is specified, create a file-backed extensible segment that disallows sharing by file-name. If pin is specified, share an extensible segment by the PIN method. Extensible segments are read/write. SEGMENT_TYPE_FILENAME (2) Create a read/write segment with sharing by the file-name method enabled, or share a read/write segment by the file-name method. filename must be specified.
in turn, uses the base-address parameter as an input parameter to allocate the segment in the same place. • Use the base-address input parameter only if it is necessary to force segment allocation to begin a flat segment at a specific address. The specified address must be a multiple of 32 kilobytes on G-series systems and a multiple of 16 kilobytes on H-series or J-series system. Avoid hard-coding the address, because the valid range of addresses can change from RVU to RVU.
of alloc_option terms available to ordinary users. For historical continuity, it also shows the TAL bit numbers. The bits are defined as follows: Value Name TAL Bit Definition 64 SEGMENT_OPTION_SHARED_ANYADDR <9> is significant only If SEGMENT_OPTION_USEBASE is specified, the segment is being shared, and the range of the requested segment is partially or completely overlapped in the current process.
4 SEGMENT_SEGID Invalid segment-id. 5 SEGMENT_SEGSIZE Invalid segment-size. 6 SEGMENT_NOSEGSPACE Unable to allocate segment space. 7 SEGMENT_NOPAGETABLE Unable to allocate segment page table space. 8 SEGMENT_SECURITY Security violation when attempting to share segment. 9 SEGMENT_INVALIDPIN pin does not exist. 10 SEGMENT_NOTOWNED pin does not have the segment allocated. 11 SEGMENT_INCEST Caller is trying to share segment with self.
• Swap file extent allocation If an extensible segment is being created, then only one extent of the swap file is allocated when SEGMENT_ALLOCATE[64]_ returns. • Segment sharing Callers of ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE[64]_ Procedures) (page 58) can share segments with callers of SEGMENT_ALLOCATE[64]_. High-PIN callers can share segments with low-PIN callers.
The SEGMENT_GET_MIN_ALIGN_ Procedure (page 1282) reports the minimum alignment for a specified segment size. This minimum alignment is recommended for all segments, and is enforced for segments in 64-bit address space. For historical compatibility, the enforced minimum alignment in 32-bit address space is a single page (16 KB on all G-, H- and J-series RVUs). For all segments, the SEGMENT_GET_PREF_ALIGN_ Procedure (page 1284) procedure reports the preferred (optimum) alignment for a specified segment size.
segment is a flat segment. The base-address parameter of the SEGMENT_USE_ Procedure (page 1298) also returns the base address of a segment. ◦ • Use the usageFlags member of the segmentInfo struct reported by the SEGMENT_GETINFOSTRUCT_ Procedure (page 1291), or the usage-flags parameter of the SEGMENT_GETINFO[64]_ Procedures (Superseded by SEGMENT_GETINFOSTRUCT_ Procedure) (page 1287).
SEGMENT_ALLOCATE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The SEGMENT_ALLOCATE_CHKPT_ procedure is called by a primary process to allocate an extended data segment for use by its backup process. Syntax for C Programmers This passive backup procedure is not supported in C programs. For a comparison of active backup and passive backup, see the Guardian Programmer's Guide.
For more information on this facility, see the Kernel-Managed Swap Facility (KMSF) Manual. • Temporary swap file If supplied, if length is not 0, and if filename is a volume name without a subvolume or file identifier, SEGMENT_ALLOCATE_CHKPT_ creates a temporary swap file on the indicated volume. If you specify a system name, it must be the system name of the local node. You can convert a temporary file to a permanent file by renaming it with the FILE_RENAME_ procedure.
error-detail output INT .EXT:ref:1 returns the error detail information returned from the backup process' call to SEGMENT_ALLOCATE_, or one of these file-system errors: 2 Segment is not allocated by the primary or the segment ID is invalid. 30 No message-system control blocks are available. 31 There is no room in the process file segment (PFS) for a message buffer in either the backup or the primary. 201 Unable to send to the backup.
• Swap file extent allocation If an extensible segment is being created, then only one extent of the swap file is allocated when SEGMENT_ALLOCATE_CHKPT_ returns. • Segment sharing Subject to security requirements, a process can share a segment with another process running on the same processor.
SEGMENT_DEALLOCATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The SEGMENT_DEALLOCATE_ procedure deallocates an extended data segment.
error-detail output INT .EXT:ref:1 returns additional information associated with some errors. For details, see Returned Value. Returned Value INT Outcome of the operation: 0 SEGMENT_OK Segment successfully deallocated. 2 SEGMENT_PARAMETER Parameter error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left. 3 SEGMENT_BOUNDS Bounds error.
• Segment deallocation When a segment is deallocated, the swap file end of file (EOF) is set to the larger of these values: • ◦ the EOF when the file was opened by SEGMENT_ALLOCATE_ ◦ the end of the highest numbered page that is written to the swap file Shared segments A shared segment remains in existence until it has been deallocated by all the processes that allocated it.
SEGMENT_DEALLOCATE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The SEGMENT_DEALLOCATE_CHKPT_ procedure is called by a primary process to deallocate an extended data segment in its backup process. Syntax for C Programmers This passive backup procedure is not supported in C programs. For a comparison of active backup and passive backup, see the Guardian Programmer's Guide.
Returned Value INT Outcome of the operation: 0 SEGMENT_OK Segment deallocated, but an I/O error occurred when writing to the segment's permanent swap file; error-detail contains the file-system error numberSegment successfully deallocated. 1 SEGMENT_FILE_ERROR Segment deallocated, but an I/O error occurred when writing to the segment's permanent swap file; error-detail contains the file-system error number.
• Segment deallocation When a segment is deallocated, the swap file end of file (EOF) is set to the larger of these values: • ◦ the EOF when the file was opened by SEGMENT_ALLOCATE_ ◦ the end of the highest numbered page that is written to the swap file Shared segments A shared segment remains in existence until it has been deallocated by all the processes that allocated it.
SEGMENT_GET_MIN_ALIGN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Minimum Permissible Alignments for 64-bit Segments Summary The SEGMENT_GET_MIN_ALIGN_ procedure computes the minimum permissible alignment for a 64-bit segment of a given size. SEGMENT_ALLOCATE64_ rejects an attempt to allocate a 64-bit segment with a specified base-address that does not satisfy the minimum alignment for its max-size.
Minimum Permissible Alignments for 64-bit Segments The returned value is log2 of the largest value <= size /4 in the sequence 16 KB, 128 KB, 1 MB, 8 MB, 64 MB, 512 MB, 4 GB, 32 GB (successive powers of 8). The resulting ranges are summarized in the following table: For size < 219 log2(min-alignment) = 14 22 <2 17 < 225 20 28 23 31 26 34 <2 29 < 237 32 else 35 <2 <2 These values are not optimal, but result in reasonable performance on all platforms and RVUs.
SEGMENT_GET_PREF_ALIGN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Summary The SEGMENT_GET_PREF_ALIGN_ procedure computes the preferred alignment for a segment of a given size. That alignment is implementation-dependent. The operating system is able to create more efficient mappings if preferred alignment is observed when assigning the base-address of a segment. NOTE: The SEGMENT_GET_PREF_ALIGN_ procedure is supported on systems running H06.
SEGMENT_GETBACKUPINFO_ Procedure Summary Syntax for TAL Programmers Parameters Returned Value Summary The SEGMENT_GETBACKUPINFO_ procedure retrieves information about an extended segment that is allocated by the backup process in a named process pair.
base-address output INT(32) .EXT:ref:1 returns the base address of the segment : • For a flat segment, base-address is different for each allocated segment. • For a selectable segment, base-address is always %2000000D (%H00080000). Returned Value INT Outcome of the operation: 0 No error. 1 Error occurred when attempting to obtain filename; error-detail contains the file-system error number.
SEGMENT_GETINFO[64]_ Procedures (Superseded by SEGMENT_GETINFOSTRUCT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The SEGMENT_GETINFO[64]_ procedures retrieve information about currently allocated data segments. The SEGMENT_GETINFO64_ procedure is a 64-bit version of the SEGMENT_GETINFO_ procedure. These procedures are superseded by SEGMENT_GETINFOSTRUCT_.
Syntax for TAL Programmers ?SOURCE $SYSTEM.SYSTEM.KMEM error := SEGMENT_GETINFO[64]_ ( segment-id ,[ segment-size ] ,[ filename:maxlen ] ,[ filename-len ] ,[ error-detail ] ,[ base-address ] ,[ usage-flags ] ); ! ! ! ! ! ! ! i o o:i o o o o Parameters segment-id input INT:value specifies the segment ID of the extended data segment for which information is to be returned. segment-size output INT(32) .EXT:ref:1 (for SEGMENT_GETINFO_) INT(64) .
error-detail output INT .EXT:ref:1 (for SEGMENT_GETINFO_) INT .EXT64:ref:1 (for SEGMENT_GETINFO64_) returns additional information associated with some errors. For details, see Returned Value. base-address output EXTADDR .EXT:ref:1 (for SEGMENT_GETINFO_) EXT64ADDR .EXT64:ref:1 (for SEGMENT_GETINFO64_) returns the base address of the segment: • For a flat segment, base-address is different for each allocated segment. • For a selectable segment, base-address is always %2000000D (%H00080000).
Returned Value INT Outcome of the operation: 0 SEGMENT_OK No error. 1 SEGMENT_FILE_ERROR Error occurred when attempting to obtain filename; error-detail contains the file-system error number. 2 SEGMENT_PARAMETER Parameter error; error-detail contains the number of the first parameter found to be in error, where 1 designates the first parameter on the left, and filename and maxlen are counted together as parameter number 3.
SEGMENT_GETINFOSTRUCT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Structure Definitions for info Considerations Summary The SEGMENT_GETINFOSTRUCT_ procedure retrieves information about a currently allocated data segment. SEGMENT_GETINFOSTRUCT_ supersedes the SEGMENT_GETINFO[64]_ procedures. NOTE: The SEGMENT_GETINFOSTRUCT_ procedure is supported on systems running H06.20 and later H-series RVUs and J06.09 and later J-series RVUs.
pin input INT specifies the PIN of the process in which to query the segment. NSK_DEFAULT_PIN (-2) indicates self. segment-id input INT refers to the segment ID of the target segment or, if -1, indicates to iterate over all segments. options INT specifies one of the following options defined in kmem.h for C and KMEM for TAL:: 0 segmentInfoDefault The default value causes all information to be returned except the filename.
This process is not privileged, is not the target process, and does not own the target process. 17 SEGMENT_PIN_REUSED The SEGMENT_GETINFOSTRUCT_ procedure is being used in iterative mode on a different process than itself and that process terminated between iterations. A different process is now using the same PIN that was used by the terminated process. Structure Definitions for info The segmentInfo structure is defined in kmem.
instance of segmentInfo, and passing as version the segmentInfoVn enumerator defined in segmentInfoVersion. The initial contents of *info are undefined, except as explained below for info->segID and info->verifier when the segID parameter is nullSegID. • If the procedure returns SEGMENT_OK (O) or SEGMENT_FILE_ERROR (1), it fills in all the accessible members of info. If it returns any other error, it makes no assignment to info.
SEGMENT_RESIZE64_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Considerations for Privileged Callers Example Related Programming Manual Summary The SEGMENT_RESIZE64_ procedure alters the size of an existing data segment (for example, a segment created by SEGMENT_ALLOCATE_ or SEGMENT_ALLOCATE64_). SEGMENT_RESIZE64_ is identical to RESIZESEGMENT except for the data type of the new-segment-size parameter, which is INT(64).
Returned Value INT A file-system error code that indicates the outcome of the call: -2 Unable to allocate page table space (not returned for unaliased segments). -1 Unable to allocate segment space. 0 Successful call; the size of the specified data segment has been changed to new-segment-size. 2 segment-id specified a nonexistent data segment, or the segment is of a type that cannot be resized (see Considerations). 12 Indicates one of these conditions.
Type of segment At segment allocate At memory access At segment resize reduced if the new size is less than the highest address of accessed memory (subject to change). • Because segment resizing is an extremely resource intensive operation, users should design their applications so that SEGMENT_RESIZE64_ is not frequently called. A good rule of thumb is to call SEGMENT_RESIZE64_ only when changing the size of a data segment by more than 128 KB.
SEGMENT_USE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary The SEGMENT_USE_ procedure selects a particular extended data segment to be currently addressable by the calling process. For selectable segments, the call to SEGMENT_USE_ must follow a call to SEGMENT_ALLOCATE_ to make the selectable extended data segment accessible.
old-segment-id output INT .EXT:ref:1 returns the segment ID of the selectable extended data segment that was previously in use. If no selectable segment was in use, a value of -1 is returned. If new-segment-id specifies a flat segment, old-segment-id returns the segment ID of the current in-use selectable segment. The flat segment and the selectable segment remain addressable by the calling process. base-address output EXTADDR .
Related Programming Manual For programming information about the SEGMENT_USE_ procedure, see the Guardian Programmer's Guide.
SEGMENTSIZE Procedure (Superseded by SEGMENT_GETBACKUPINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The SEGMENTSIZE procedure returns the size of the specified segment in bytes. Syntax for C Programmers This procedure does not have a C syntax, because it is superseded and should not be used for new development.
SENDBREAKMESSAGE Procedure (Superseded by BREAKMESSAGE_SEND_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The SENDBREAKMESSAGE procedure allows user processes to send break-on-device messages to other processes.
Considerations • A successful status indication from SENDBREAKMESSAGE does not imply that the process has received the message, only that it has been sent. • If the process-id designates a member of a named process pair, the break-on-device message delivery will automatically be retried to the backup process if a failure or path switch occurs. • A break-on-device system message is delivered to the $RECEIVE file of the target process.
SET^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Operations Examples Related Programming Manual Summary The SET^FILE procedure alters file characteristics and checks the old values of those characteristics being altered. SET^FILE is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
For other callers, the procedure definition is: error := SET^FILE ( { common-fcb } { file-fcb } ,operation ,[ new-value ] ,[ old-value ] ); ! ! ! ! ! i i i i o Parameters common-fcb input INT:ref:* identifies those files whose characteristics are to be altered. The SET^FILE operations that make sense only for the common-fcb are the SET^BREAKHIT, SET^ERRORFILE, and SET^TRACEBACK.
Returned Value INT A file-system or SIO procedure error code that indicates the outcome of the call. If abort-on-error mode is in effect, the only possible error code is 0. Operations Table 42 lists operations that set values in the new-value parameter. Table 43 lists operations that set addresses. For pTAL callers, addresses are set in the setaddr-value parameter. For other callers, addresses are set in the new-value parameter.
Table 42 SET^FILE Operations That Set Values (continued) operation Description of Operation Requested new-value old-value State of File must be omitted must be omitted Closed must be omitted must be omitted Closed When set alone without ASSIGN^PRIEXT, this operation sets only the default values; it comes into effect only when a ASSIGN^PRIEXT is set. INIT^FILEFCB Specifies that the file FCB be initialized. This operation is not used when the INITIALIZER procedure is called to initialize the FCBs.
Table 42 SET^FILE Operations That Set Values (continued) operation Description of Operation Requested new-value old-value State of File is 1000, which corresponds to an increment of 1. The possible EDIT line numbers are from 0 to 99999.999 SET^EDITREAD^REPOSITION Specifies that this READ^FILE is to begin must be at the position set in the sequential block omitted buffer (second through fourth words).
Table 42 SET^FILE Operations That Set Values (continued) operation Description of Operation Requested SET^READ^TRIM Sets or clears read-trailing-blank-trim for new-state the file. If on, the count-read parameter does not account for trailing blanks. SET^SYSTEMMESSAGES .<15> = unused new-value old-value State of File state Open new-sys-msg-mask sys-msg-mask Open The user replies to the system messages designated by this operation by using WRITE^FILE.
Table 43 describes operations that set addresses. For pTAL callers, addresses are set in the setaddr-value parameter. For other callers, addresses are set in the new-value parameter. Table 43 SET^FILE Operations That Set Addresses operation Description of Operation Requested SET^SYSTEMMESSAGESMANY Sets system message reception for the $RECEIVE file. sys-msg-mask-words is a four-word mask. Setting a bit in sys-msg-mask-words indicates that the corresponding message is to pass back to the user.
Table 43 SET^FILE Operations That Set Addresses (continued) operation Description of Operation Requested .<8> memory lock failure message (NonStop II systems only) .<9:13> unused .<14> open message .<15> close message setaddr-value old-value State of File or new-value SET^SYSTEMMESSAGESMANY sys-msg-mask-words[2] (word 2) .<0> CONTROL message .<1> SETMODE message .<2> RESETSYNC message .<3> CONTROLBUF message .<4:7> unused .
Related Programming Manual For programming information about the SET^FILE procedure, see the Guardian Programmer's Guide.
SETJMP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Example Related Programming Manual Summary The SETJMP_procedure saves process context in a jump buffer. This context is used when a nonlocal goto is performed by a corresponding call to the LONGJMP_ procedure. Syntax for C Programmers #include jmp_buf env; int setjmp ( jmp_buf env ); Syntax for TAL Programmers ?SOURCE $SYSTEM.ZGUARD.
where env is a valid variable name. Alternatively, you can allocate the buffer by declaring a structure of type JMP_BUF_TEMPLATE. In either case, the buffer must be accessible to both the SETJMP_ procedure call and the associated LONGJMP_ procedure call. • The jump buffer saved by the SETJMP_ procedure is normally used by a call to the LONGJMP_ procedure. The jump buffer can be used by a call to the SIGLONGJMP_ procedure only if the signal mask is not required.
SETLOOPTIMER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Example Summary The SETLOOPTIMER procedure sets the caller's "process loop-timer" value. A positive loop-timer value enables process loop timing by the operating system and specifies a limit on the total amount of processor time the calling process is allowed.
Condition Code Settings < (CCL) indicates that the new-time-limit parameter is omitted or is specified as a negative value. The state of process loop timing and the setting of the process' loop timer are unchanged. = (CCE) indicates that the new-time-limit value is set into the process' loop timer and that loop timing is enabled. > (CCG) is not returned from SETLOOPTIMER. Considerations • Process processor time Using SETLOOPTIMER to measure process processor time is not recommended.
SETMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Functions Considerations Disk File Considerations Interprocess Communication Considerations Messages Examples Related Programming Manuals Summary The SETMODE procedure is used to set device-dependent functions. A call to the SETMODE procedure is rejected with an error indication if incomplete nowait operations are pending on the specified file.
Parameters filenum input INT:value is a number of an open file that identifies the file to receive the SETMODE function. function input INT:value is one of the device-dependent functions listed in Table 44 (page 1319). param1 input INT:value is one of the parameters listed in Table 44 (page 1319). If omitted, for a disk file the present value is retained. For SETMODEs on other devices, this value depends on the device and the value supplied in the function parameter.
Functions Table 44 lists the SETMODE functions that can be used with the I/O devices discussed in this manual for NonStop servers. Table 44 SETMODE Functions Function Parameters and Effect 1 Disk: Set file security param1 <0> =1 for program files only, sets accessor's ID to program file's ID when program file is run (PROGID option). <1> =1 sets CLEARONPURGE option on. This means all data in the file is physically erased from the disk (set to zeros) when the file is purged.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 3 Disk: Set write verification param1 <15> =0 verified writes off (default). =1 verified writes on. param2 is used with DP2 disk files only. param2 4 =0 change the open option setting of the verify writes option (default). =1 change the file label default value of the verify writes option. Disk: Set lock mode. Note that this operation is not supported for queue files.
Table 44 SETMODE Functions (continued) Function Parameters and Effect If param1.<15> is 0, then param2 =0 adds CR =1 adds nothing (invalid for device subtypes 1, 3, 4, 5, and 6; disables DEV COMPRESS attribute in spooler) Ifparam1.<15> is 1, then param2 7 =0 adds CR/LF =1 is invalid (might return error) Terminal: Set system auto line feed after receipt of carriage return line termination (default mode is configured) param1.
Table 44 SETMODE Functions (continued) Function Parameters and Effect param2 =0 normal mode (any type file access is permitted) =1 BREAK mode (only BREAK-type file access is permitted) See "Communicating With Terminals," and "Writing a Terminal Simulator," in the Guardian Programmer's Guide. 12 Terminal: Set terminal access mode param1.
Table 44 SETMODE Functions (continued) Function Parameters and Effect =4 baud rate =150 =5 baud rate = 300 =6 baud rate = 600 =7 baud rate = 1200 =8 baud rate = 1800 =9 baud rate = 2000 = 10 baud rate = 2400 = 11 baud rate = 3600 = 12 baud rate = 4800 = 13 baud rate = 7200 = 14 baud rate = 9600 = 15 baud rate = 19200 = 16 baud rate = 200 = 17 baud rate = 38400 (5577 printer only) param2 is not used with function 22 except when specifying split baud rates with the LIU-4 controlle
Table 44 SETMODE Functions (continued) Function Parameters and Effect param2 = 141 TX baud rate = 7200 = 142 TX baud rate = 9600 = 143 TX baud rate = 19200 = 144 TX baud rate = 200 =0 RX baud rate = 50 =1 RX baud rate = 75 =2 RX baud rate = 110 =3 RX baud rate = 134.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 25 Line printer (subtype 3): Set form length param1 = length of form in lines param2 is not used with function 25. 26 Line printer (subtype 3): Set or clear vertical tabs param1 NOTE: =0 is (line#-1) of where tab is to be set. = -1 clear all tabs (except line 1). A vertical tab stop always exists at line 1 (top of form). param2 is not used with function 26. 27 Line printer or terminal: Set system spacing mode param1.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 31 Set packet mode param1.<0> param2 32 =0 ignore param2. =1 param2 specifies leading packet size. =0 use default packet size for transmission (default). >0 is size of first outgoing packet in each WRITE or WRITEREAD request. It must be smaller than the configured packet size. Set X.25 call setup parameters .<0> param1 .<1> .<2> .<8:15> =0 do not accept charge. =1 accept charge. =0 do not request charge.
Table 44 SETMODE Functions (continued) Function Parameters and Effect .<8> .<10> .<11> .<12> CID, cable = 0 identification =1 new cable =0 not moving =1 paper moving =0 not at bottom =1 at bottom TOF, top of = 0 form not at top PMO, paper motion BOF, bottom of form =1 .<13> .<14> .<14> .
Table 44 SETMODE Functions (continued) Function Parameters and Effect .<12> .<13> .<14> .<15> buffer full paper out device power on device not ready =0 not full =1 full =0 OK =1 paper out =0 OK =1 POWER ON error =0 ready =1 not ready All other last-params [0] bits are undefined. last-params[1] auxiliary status word if last-params[0].<9:11> = 7; auxiliary status word is as follows: .<9:13> auxiliary status .
Table 44 SETMODE Functions (continued) Function Parameters and Effect .<14> .<15> last-params[1] =0 OK =1 device power on error =0 OK =1 device not ready auxiliary status word if last-params[0].<10:12> = 7; auxiliary status word is as follows: .<0:7> undefined .<8:11> fault display status (most significant hex digit) .<12:15> fault display status (least significant hex digit) Fault display status summary: 38 Operator Display Aux Status .<8:11> Aux Status .
Table 44 SETMODE Functions (continued) Function Parameters and Effect NOTE: Although the cursor typically will not move when 0 or 1 is specified for param1, these options do not turn off ECHO. Therefore, if the termination character is one which would normally cause cursor movement (such as a LF or CR) and ECHO is enabled, cursor movement will occur. SETMODEs 40-49 are reserved for the Exchange products. For details, see the Exchange reference manuals.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 59 Return count of bytes read param1 = count of actual bytes read param2 = 0 66 Tape drive: Set density param1 =0 800 bpi (NRZI) =1 1600 bpi (PE) =2 6250 bpi (GCR) =3 as indicated by switches on tape drive =8 38000 bpi param2 is not used with function 66. 67 AUTODCONNECT for full-duplex modems: Monitor carrier detect or data set ready param1 =0 disable AUTODCONNECT (default setting). =1 enable AUTODCONNECT.
Table 44 SETMODE Functions (continued) Function Parameters and Effect last-params reflects the current effective SETMODE function 72 value for this file, which is either 1 or 2, and not 0. This is applicable for systems running J06.05 and later J-series RVUs and H06.16 and later H-series RVUs. For example, if the USERIOBUFFER_ALLOW_ procedure is called before the file is opened, the last-params will return 2. (Some nowaited write operations on the file with alternate keys will be forced to wait.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 92 Disk: Set maximum number of extents for a nonpartitioned file. (Function 92 is invalid for audit-trail files and for partitioned non-key-sequenced files.) param1 = new maximum number of extents value. There is no guarantee of success if you specify a value greater than 500. The default is 16 extents. param2 is not used with function 92.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 99 TAPEPROCESS error recovery method param1 =0 record level recovery (default). The record is written to tape as soon as it is received. =1 file level recovery. Data is buffered at the drive until an end-of-file mark is received. The data is then flushed from the drive buffer to the tape media. =2 volume level recovery.
Table 44 SETMODE Functions (continued) Function Parameters and Effect 117 Process files: Set TRANSID forwarding param1 =0 normal mode (default for process subtypes other than 30 and 31): If a transaction identifier is in effect at the time of a write, read, or writeread on the process file, it is sent with the request so that the receiver will operate under the transaction.
Table 44 SETMODE Functions (continued) Function Parameters and Effect The two words are combined to form a 32-bit integer for the timeout value. These values are reserved: -2D = system default period (60 seconds) -1D = infinite timeout period (timeout error is not returned) 0D = no timeout period (error is returned immediately if record cannot be read) All other negative values are invalid. Note that SETMODE function 128 is valid for queue files only.
Table 44 SETMODE Functions (continued) Function Parameters and Effect If the file is audited and structured, the file must be opened with an access mode of read-only. The exclusion mode can be shared, protected, or exclusive. If the exclusion mode is shared, updates done by other openers of the file might not be seen by this opener. If the file is audited and unstructured, only read operations can be performed on the file after this SETMODE is issued with param1 set to 1.
Table 44 SETMODE Functions (continued) Function Parameters and Effect NOTE: These printers do not come equipped with the IBM PC character set; it can be installed later. To use this operation, the printer must have the IBM PC character set installed on the printer. If the printer does not have the IBM PC character set installed, the printer ignores SETMODE function 142. 144 Sets LU character set and double-byte character code param1 must be omitted for function 144.
Table 44 SETMODE Functions (continued) Function Parameters and Effect =1 automatic locking: writes of record with alternate keys are locked at the beginning of insertion and unlocked after all associated alternate key record insertions are complete. This prevents interference from programs attempting concurrent update of the same record. param2 must be zero if supplied. SETMODE function 149 is not valid (nor needed) for audited files.
Table 44 SETMODE Functions (continued) Function Parameters and Effect By default, checksums are validated from disk I/O operations. SETMODE function 158 request is ignored for outstanding read operations. The file must be opened with unstrusctured-access option specified, even if the file is unstructured. Function 158 does not support alternate-key files or partitions.
Table 44 SETMODE Functions (continued) Function Parameters and Effect ER mode is supported only by the SNAX/XF product. Specifying this function for SNALU causes an error 2 (invalid operation) to be returned. Passing a value other than one of those listed above causes an error 590 (invalid parameter value) to be returned. A SETMODE function 165 call applies only to the opener, not to the device that is opened; another SETMODE function 165 call must be made if the file is closed.
Table 44 SETMODE Functions (continued) Function Parameters and Effect =1 enables processing of CTRL-C (03 hex) as break character. Equivalent startup option is -BREAKDATA (default). param2 is not used with function 263 Note that IAC BREAK will still be processed. For more information about -BREAKDATA and -NOBREAKDATA, see the Telserv Guide. 264 Telserv: Enables/disables processing of CTRL-S and CTRL-Q characters as XON and XOFF.
Considerations • Default SETMODE settings The SETMODE settings designated as "default" are the values that apply when a file is opened (not if a particular function is omitted when SETMODE is called). • Waited SETMODE The SETMODE procedure is used on a file as a waited operation even if filenum has been opened for nowait. Use the SETMODENOWAIT procedure for nowait operations. • No SETMODE calls on Telserv are allowed before doing a CONTROL operation 11.
. CALL SETMODE ( FNUM , 1 , SECURITY ); 2. This LITERAL sets the file's security so that the file's owner ID is used by the calling process as its process access ID when the program file is run: read = owner only write = owner only execute = any local user purge = owner only LITERAL PROG^SEC = %102202; . . .
SETMODENOWAIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manuals Summary The SETMODENOWAIT procedure is used to set device-dependent functions in a nowait manner on nowait files. Whereas the SETMODE procedure is a waited operation and suspends the caller while waiting for a request to complete, the SETMODENOWAIT procedure returns to the caller after initiating a request.
Syntax for TAL Programmers CALL SETMODENOWAIT ( filenum ,function ,[ param1 ] ,[ param2 ] ,[ last-params ] ,[ tag ] ); ! ! ! ! ! ! i i i i o i Parameters filenum input INT:value is a number of an open file, identifying the file to receive the SETMODENOWAIT function. function input INT:value is one of the device-dependent functions listed in Table 44 (page 1319) for the SETMODE procedure. param1 input INT:value is one of the param1 values listed in Table 44 (page 1319) for the SETMODE procedure.
Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that the SETMODENOWAIT is successful. > (CCG) indicates that the SETMODENOWAIT function is not allowed for this device type. Considerations • File opened with wait depth > 0 AWAITIO[X] must be called to complete the call when filenum is opened with a wait depth greater than 0.
SETMYTERM Procedure (Superseded by PROCESS_SETSTRINGINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The SETMYTERM procedure permits a process to change the terminal that is used as its home terminal (the default home terminal is the home terminal of a process' creator).
SETPARAM Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Related Programming Manuals Summary The SETPARAM procedure is used to set and fetch various values such as the station characteristics of network addresses. The operation can be performed in a nowait manner by use of the nowait-tag parameter and in that case is completed by a call to AWAITIO[X].
function input INT:value is one of these SETPARAM function codes: 1 Set or fetch a remote data terminal equipment address (use with X.25 Access Method (X25AM) only). 2 Set or fetch the clear cause or diagnostic bytes (use with X25AM only). 3 Set or fetch parameters for BREAK handling. 4 Set or fetch the reset cause or diagnostic bytes (use with X25AM only). 5 Fetch the restart cause or diagnostic bytes (use with X25AM only).
last-param-max input INT:value is the maximum number of bytes that can be placed in last-param-array . The default is 256. nowait-tag input INT(32):value if present and not -1D, specifies that the operation is to be performed in a nowait manner and specifies the value to be returned in the tag parameter of AWAITIO[X] at completion. If nowait-tag is omitted, or is -1D, or the file has a nowait depth of 0, the operation is waited and is complete when the procedure returns. See Considerations.
parameter of SETPARAM; the count-transferred parameter of AWAITIO[X] returns the number of bytes returned in last-param-array. Example The following example fetches the protocol ID field in the outgoing call request packet. Four bytes of data return. CALL SETPARAM ( FNUM , 8 , , , OLD^PARAMS , OLD^SIZE ); Related Programming Manuals For programming information about the SETPARAM procedure, see the data communication manuals.
SETSTOP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations OSS Considerations Example Related Programming Manual Summary The SETSTOP procedure permits a process to protect itself from being deleted by any process other than itself or its creator.
Returned Value INT Either the preceding value of stop-mode or -1 if an invalid mode was specified. Considerations • The default stop mode is 1 when a process is created. • If a process' stop mode is 1 when a PROCESS_STOP_ or STOP procedure call is issued against it by a process without the authority to stop it, the process does not stop; the process is deleted, however, if and when the stop mode is changed to 0.
SETSYNCINFO Procedure (Superseded by FILE_SETSYNCINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary The SETSYNCINFO procedure is used by the backup process of a process pair after a failure of the primary process. The SETSYNCINFO procedure passes a process pair's latest synchronization block (received in a checkpoint message from the primary) to the file system.
Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that SETSYNCINFO is successful > (CCG) indicates that the file is not a disk file. Considerations • The SETSYNCINFO procedure cannot be used with files that are larger than approximately 2 gigabytes, including both Enscribe format 2 and OSS files. If an attempt is made to use the SETSYNCINFO procedure with these files, error 581 is returned.
SETSYSTEMCLOCK Procedure (Superseded by the SYSTEMCLOCK_SET_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Condition Code Settings Example Related Programming Manual Summary The SETSYSTEMCLOCK procedure allows you to change the system clock if you are a member of the super group. As of the H06.25 and J06.14 RVUs, SETSYSTEMCLOCK is superseded by the SYSTEMCLOCK_SET_ Procedure (page 1408), which calls the same parameters.
Example CALL SETSYSTEMCLOCK ( JULIAN^GMT , MODE , TUID ); Related Programming Manual For programming information about the SETSYSTEMCLOCK procedure, see the Guardian Programmer's Guide.
SHIFTSTRING Procedure (Superseded by STRING_UPSHIFT_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The SHIFTSTRING procedure upshifts or downshifts all alphabetic characters in a string. Nonalphabetic characters remain unchanged.
Related Programming Manual For programming information about the SHIFTSTRING utility procedure, see the Guardian Programmer's Guide.
SIGACTION_ Procedure NOTE: This procedure can be called only from native processes. SIGACTION_ is the pTAL procedure name for the C sigaction() function. The C sigaction() function complies with the POSIX.1 standard. For the pTAL prototype definitions, see the $SYSTEM.SYSTEM.HSIGNAL header file. For a discussion of each parameter and procedure considerations, see the sigaction(2) function reference page either online or in the Open System Services System Calls Reference Manual.
SIGACTION_INIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Handler Considerations Examples Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGACTION_INIT_ procedure establishes the caller's initial state of signal handling if default handling is not desired. Syntax for C Programmers #include
Considerations • This procedure is the functional equivalent of the TNS ARMTRAP procedure for native processes. • POSIX.1 compliance This procedure is an extension to the POSIX.1 standard. The same effect can be achieved while maintaining compliance with the POSIX.1 standard by calling the SIGPROCMASK_ procedure and a loop of SIGACTION_ procedure calls. • Calling considerations The SIGACTION_INIT_ procedure is designed to be called once, typically from the main procedure of a program.
Handler Considerations • The handler parameter must be one of these: ◦ The address of an untyped native procedure that accepts these three parameters. These parameters are passed to the handler by the system when the handler is invoked to catch a signal: – SIGNUM An INT(32) numeric value indicating the signal that caused the handler to be invoked. – SIGINFO A pointer whose value is currently NULL. – UCONTEXT A pointer to a structure of type UCONTEXT_T.
Examples C Example if (SIGACTION_INIT_ ( myhandler ) != 0) /* handle error */ TAL Example error := SIGACTION_INIT_ ( @SIG_HANDLER ); IF error=<>0 THEN errnoval := ERRNO_GET_; Related Programming Manual For programming information about the SIGACTION_INIT_ procedure, see the Guardian Programmer's Guide.
SIGACTION_RESTORE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGACTION_RESTORE_ procedure restores the signal-handling state saved by a previous call to the SIGACTION_SUPPLANT_ procedure. SIGACTION_SUPPLANT_ allows a subsystem (such as a shared run-time library) to take over signal handling temporarily.
Considerations • The SIGACTION_RESTORE_ procedure validates the buffer indicated by signal-buffer and returns an error if the buffer is invalid. It is assumed that the buffer has been initialized by the SIGACTION_SUPPLANT_ procedure and that it has not been modified by the caller. • The signal-handling state previously saved in the buffer indicated by signal-buffer is atomically restored.
SIGACTION_SUPPLANT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGACTION_SUPPLANT_ procedure allows a subsystem (such as a shared run-time library) to take over signal handling temporarily.
length input INT:value specifies the size in bytes of the buffer indicated by signal-buffer. Returned Value INT(32) Outcome of the call: 0D Successful outcome. -1D An error occurred. The reason for the error is given in the errno variable. FE_EFAULT The address in signal-buffer is out of bounds. FE_EINVAL SIG_IGN or SIG_ERR is passed to the handler. FE_ERANGE length is less than the minimum required. Use the ERRNO_GET_ procedure to obtain the value of errno in a Guardian process.
If SIGACTION_SUPPLANT_ returns an error, the signal-handling state is not changed. • All signals, except those for which you cannot install a handler, are blocked. Deferrable signals that occur while the process is executing privileged code are deferred until the process exits privileged execution mode. If these signals are not blocked, they are then delivered to the handler, which is activated at the tip of the main stack. Nondeferrable signals are immediately delivered to the specified handler.
SIGADDSET_ Procedure SIGDELSET_ Procedure SIGEMPTYSET_ Procedure SIGFILLSET_ Procedure SIGISMEMBER_ Procedure NOTE: These procedures can be called only from native processes. These procedure names are the pTAL names for the corresponding C functions: Procedure Name Corresponding C Function SIGADDSET_ sigaddset() SIGDELSET_ sigdelset() SIGEMPTYSET_ sigemptyset() SIGFILLSET_ sigfillset() SIGISMEMBER_ sigismember() These functions comply with the POSIX.1 standard.
SIGJMP_MASKSET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Examples Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGJMP_MASKSET_ procedure saves a signal mask in a jump buffer that has already been initialized by the SIGSETJMP_ procedure.
If NULL, causes the signal mask in the jump buffer indicated by env to be cleared. A subsequent call to the SIGLONGJMP_ procedure restores the context contained in the jump buffer, including the clear signal mask that unblocks all signals. Returned Value INT(32) Outcome of the call: 0D Successful outcome. -1D An error occurred. The reason for the error is given in the errno variable: FE_EINVAL The jump buffer has not been initialized.
SIGLONGJMP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGLONGJMP_ procedure performs a nonlocal goto. It restores the state of the calling process using context saved in a jump buffer by the SIGSETJMP_ procedure. Control returns to the location of the corresponding SIGSETJMP_ procedure call.
Considerations • SIGLONGJMP_ is the TAL or pTAL procedure name for the C siglongjmp() function. The C siglongjmp() function complies with the POSIX.1 standard. • SIGLONGJMP_ does not return. Normally, return is made through the corresponding SIGSETJMP_ procedure. • Restoring the signal mask with this procedure enables a native process to receive multiple occurrences of the same nondeferrable signal when this procedure is used to exit a signal handler.
SIGNAL_ Procedure NOTE: This procedure can be called only from native processes. SIGNAL_ is the pTAL procedure name for the C signal() function. The C signal() function complies with the POSIX.1 standard. For the pTAL prototype definitions, see the $SYSTEM.SYSTEM.HSIGNAL header file. For a discussion of each parameter and procedure considerations, see the signal(3) function reference page either online or in the Open System Services Library Calls Reference Manual.
SIGNALPROCESSTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Messages Example Related Programming Manual Summary The SIGNALPROCESSTIMEOUT procedure sets a timer based on process execution time, as measured by the processor clock. When the time expires, the calling process receives an indication in the form of a system message on $RECEIVE.
param1 input INT:value identifies the timeout message read from $RECEIVE. param2 input INT(32):value identifies the timeout message read from $RECEIVE (same purpose as param1). tag output INT:ref:1 returns an identifier associated with the timer. This tag should be used only to call the CANCELPROCESSTIMEOUT procedure. Condition Code Settings < (CCL) indicates that SIGNALPROCESSTIMEOUT is unable to allocate a time-list element (TLE). = (CCE) indicates that SIGNALPROCESSTIMEOUT is successful.
Messages • Timeout message When a time-list element (TLE) set by a call to the SIGNALPROCESSTIMEOUT procedure times out, a system message -26 (process time timeout) is placed on the $RECEIVE queue to be read by the caller. (This message is identical to the message generated by SIGNALTIMEOUT except that the message number is different.
SIGNALTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Messages Example Related Programming Manual Summary The SIGNALTIMEOUT procedure sets a timer to a given number of units of elapsed time, as measured by the processor clock. When the time expires, the calling process receives an indication in the form of a system message on $RECEIVE.
param1 input INT:value identifies the timeout message read from $RECEIVE. param2 input INT(32):value identifies the timeout message read from $RECEIVE (same purpose as param1). tag output INT:ref:1 returns an identifier associated with the timer. This tag should be used only to call the CANCELTIMEOUT procedure. Condition Code Settings < (CCL) indicates that SIGNALTIMEOUT is unable to allocate a time list element (TLE). This can occur if fewer than one-fourth of the TLEs are free.
When the timer expires (that is, when a timeout message is delivered to $RECEIVE), your application can compute the remaining time and set another timer for the short interval that remains. However, because the possibility of clock discrepancy becomes greater as the interval being timed becomes longer, it would be even safer to measure a long time interval by dividing it into a series of relatively short intervals.
SIGPENDING_ Procedure NOTE: This procedure can be called only from native processes. SIGPENDING_ is the pTAL procedure name for the C sigpending() function. The C sigpending() function complies with the POSIX.1 standard. For the pTAL prototype definitions, see the $SYSTEM.SYSTEM.HSIGNAL header file. For a discussion of each parameter and procedure considerations, see the sigpending(2) function reference page either online or in the Open System Services System Calls Reference Manual.
SIGPROCMASK_ Procedure NOTE: This procedure can be called only from native processes. SIGPROCMASK_ is the pTAL procedure name for the C sigprocmask() function. The C sigprocmask() function complies with the POSIX.1 standard. For the pTAL prototype definitions, see the $SYSTEM.SYSTEM.HSIGNAL header file. For a discussion of each parameter and procedure considerations, see the sigprocmask(2) function reference page either online or in the Open System Services System Calls Reference Manual.
SIGSETJMP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Related Programming Manual Summary NOTE: This procedure can be called only from native processes. The SIGSETJMP_ procedure saves process context in a jump buffer. This context is used when a nonlocal goto is performed by a corresponding call to the SIGLONGJMP_ procedure. Optionally, this procedure also saves the current signal mask. Syntax for C Programmers #include
mask input INT(32):value specifies whether the current signal mask is also saved in the jump buffer indicated by env: 0D specifies that the current signal mask is not to be saved. < >0D specifies that the current signal mask is to be saved. This mask is reinstated by a corresponding call to the SIGLONGJMP_ procedure. Returned Value INT(32) Outcome of the call: 0D SIGSETJMP_ procedure was called directly. < >0D SIGSETJMP_ is returning as a result of a call to the SIGLONGJMP_ procedure.
SIGSUSPEND_ Procedure NOTE: This procedure can be called only from native processes. SIGSUSPEND_ is the pTAL procedure name for the C sigsuspend() function. The C sigsuspend() function complies with the POSIX.1 standard. For the pTAL prototype definitions, see the $SYSTEM.SYSTEM.HSIGNAL header file. For a discussion of each parameter and procedure considerations, see the sigsuspend(2) function reference page either online or in the Open System Services System Calls Reference Manual.
SSIDTOTEXT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The SSIDTOTEXT procedure converts the internal format subsystem ID to the external representation. Syntax for C Programmers #include short SSIDTOTEXT ( short ssid ,char *chars ,[__int32_t *status ] ); Syntax for TAL Programmers len := SSIDTOTEXT ( ssid ,chars ,[ status ] ); ! i ! o ! o Parameters ssid INT .
-3 file not key-sequenced -4 file has wrong record size -5 file has wrong primary key definition (3,x) Error reading nonresident template file; x is the file-system error. (4,0) Invalid value in internal subsystem ID. (7,x) Error accessing private segment; x is the MOVEX error code. (8,0) Internal error. Returned Value INT Number of characters placed into chars. Zero is returned if one of the errors (0,29), (4,0), or (8,0) occurs.
STACK_ALLOCATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Examples Summary The STACK_ALLOCATE_ procedure allocates a user stack segment for use as a thread or alternate signal stack.
• The STACK_ALLOCATE_ procedure is only supported in pTAL; it is not supported in TAL. Parameters stacksize input, output INT(32) .EXT:ref:1 specifies the overall stack size in bytes (which includes all the components of the stack) and returns the size actually allocated. The unsigned integer input value is rounded up to a multiple of the memory page size (16 KB) and may be adjusted further as needed to satisfy the minimum size of each component. If any error is returned, stacksize is unchanged.
Returned Value INT Outcome of the operation: 0 Operation was successful; stackaddr contains base address of the stack, and stacksize contains the rounded stack size. 1 Cannot allocate Kernel-Managed Swap space. 2 An invalid option value was specified 3 A bounds violation on parameter. 5 Requested stacksize or guardsize is too large to handle; overall stack size limit is USERSTACK_MAX (16MB, defined in kmem.h). 15 Address space is unavailable.
STACK_DEALLOCATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Example Summary The STACK_DEALLOCATE_ procedure releases memory resources for a user stack that was allocated using the STACK_ALLOCATE_ procedure. The stack specified by the stackaddr parameter must have been allocated as a user stack in an earlier call to the STACK_ALLOCATE_ procedure or an error is returned.
Example error=STACK_DEALLOCATE_(stackaddr); 1394 Guardian Procedure Calls (S)
STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Messages Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The STEPMOM procedure is called by a process when it wants to receive process deletion (STOP or ABEND) messages for a process it did not create.
Syntax for TAL Programmers CALL STEPMOM ( process-id ); ! i Parameters process-id input INT:ref:4 is a four-word array containing the process ID of an already executing process, for which the calling process wants to receive the process deletion message. The process ID is a four-word array, where: [0:2] [3] Process name or creation timestamp .<0:3> Reserved .<4:7> Processor number where the process is executing .
OSS Considerations If STEPMOM is used to set the mom of an OSS process, the new mom receives the Guardian process deletion message when the OSS process terminates. The message indicates that the terminated process was an OSS process and contains the OSS process ID; otherwise, the message is the same as one received for a terminating Guardian process. If the OSS process successfully executes one of the OSS exec or tdm_exec set of functions, a Guardian process deletion message is sent to the mom.
STOP Procedure (Superseded by PROCESS_STOP_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations NetBatch Considerations OSS Considerations Messages Examples Related Programming Manual Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The STOP procedure deletes a process or process pair and indicates that the deletion was caused by a normal condition.
Parameters process-id input INT:ref:4 indicates the process that is to be stopped: • omitted (or zero), meaning "stop myself," or • the four-word array containing the process ID of the process to be stopped, where: [0:2] [3] Process name or creation timestamp .<0:3> Reserved .<4:7> Processor number where the process is executing .
termination-info input INT:value can be provided as an option by the calling process if it is a subsystem process that defines Subsystem Programmatic Interface (SPI) error numbers. If supplied, this parameter must be the SPI error number that identifies the error that caused the process to stop itself. For more information on the SPI error numbers and subsystem IDs, see the SPI Programming Manual. If termination-info is not specified, this field is zero.
• Rules for stopping a Guardian process: process access IDs and creator access IDs ◦ If the process is a local process and the request to stop it is also from a local process, these user IDs or associated processes may stop the process: – local super ID – the process' creator access ID (CAID) or the group manager of the CAID – the process' process access ID (PAID) or the group manager of the PAID ◦ If the process is a local process, a remote process cannot stop it.
you try to create a new process with the same name. The best way to be sure that a process has terminated is to wait for the process deletion message. • Stopping a process that has the Inspect or saveabend attribute set If the process being stopped has either the Inspect attribute or the saveabend attribute set, and if DMON exists, STOP returns error 0 but deletion of the process is delayed until DMON approves it.
Messages • Process deletion (STOP) message The creator of the stopped process is sent a system message -5 (process deletion: STOP), indicating that the deletion occurred. For the format of the interprocess system messages, see the Guardian Procedure Errors and Messages Manual. Examples CALL STOP; CALL STOP ( ProcID ); ! stop me. ! stop the process that has ! this process ID. Related Programming Manual For programming information on batch processing, see the NetBatch User's Guide.
STRING_UPSHIFT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The STRING_UPSHIFT_ procedure changes all the alphabetic characters in a string to upper case. Nonalphabetic characters remain unchanged.
3 Bounds error. 4 String too large to fit in out-string. Example err := STRING_UPSHIFT_ ( in^string:len, out^string:maxlen ); Related Programming Manual For programming information about the STRING_UPSHIFT_ procedure, see the Guardian Programmer's Guide.
SUSPENDPROCESS Procedure (Superseded by PROCESS_SUSPEND_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Considerations OSS Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The SUSPENDPROCESS procedure puts a process or process pair into the suspended state, preventing that process from being active (that is, executing instructions).
Considerations • When SUSPENDPROCESS is called on a Guardian process, the caller must either have the same process access ID as the process or process pair it is attempting to suspend, have super ID, or be the group manager of the process access ID. For information about system security, specifically the process access ID and super ID, see the Guardian User's Guide.
SYSTEMCLOCK_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Adjusting the Clock Using Modes 0, 1, 2, 3, and 6 Stopping Time Adjustment Adjusting Clock Rates Using Modes 9 and 10 Using TUID System Clock System Message Clock Subsystem EMS Events Clock Adjustment Queries Example Related Programming Manual Summary The SYSTEMCLOCK_SET_ procedure allows you to adjust or set the system clock if you are a member of the super group.
mode input INT:value specifies the mode and source as follows: Mode ZSYSTAL identifier Action julian-gmt Value 0 ZSYS^VAL^SCS^OPR^IN^ABS set/adjust time absolute GMT 1 ZSYS^VAL^SCS^HRDWR^CLK^ABS set/adjust time absolute GMT 2 ZSYS^VAL^SCS^OPR^IN^REL set/adjust time relative GMT 3 ZSYS^VAL^SCS^HRDWR^CLK^REL set/adjust time relative GMT 5 ZSYS^VAL^SCS^FORCE^SET^REL set time relative GMT 6 ZSYS^VAL^SCS^FORCE^ADJ^REL adjust time relative GMT 7 ZSYS^VAL^SCS^FORCE^SET^ABS set time a
tuid input INT:value is a time update ID obtained from the JULIANTIMESTAMP procedure. It should be used with relative-GMT modes to avoid conflicting changes. Returned Value INT Outcome of the operation. Beginning with the H06.25 and J06.14 RVUs, result-code literal identifiers are defined in ZSYSTAL, as shown, and in ZSYSC, where the names are the same except _ replaces ^. These header files are installed in the ZSYSDEFS subvolume. 0 ZSYS^VAL^SCS^OK Success.
Adjusting the Clock Using Modes 0, 1, 2, 3, and 6 The system adjusts the clock by very small amounts. Small changes are applied at the rate of one microsecond every 75 milliseconds (J- or H- series) or every 300 milliseconds (G-series). Moderate changes are applied over a five-minute period. The maximum retard and advance rate is -400 PPM and +4000 PPM on TNS/E, or -100 PPM and +1000 PPM on TNS/R.
• If a tuid parameter is passed to SYSTEMLOCK_SET_, its value must match TUID, or the call is rejected with an error. • The principal use of the tuid parameter is to ensure that a relative julian-gmt parameter was not made obsolete by an intervening time set. However, a tuid parameter can be passed, and will be checked, with any mode. System Clock System Message When the time is reset (but not when it is adjusted), each enabled process receives the SETTIME system message (-10).
SYSTEMENTRYPOINT_RISC_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary NOTE: The pTAL syntax for this procedure is declared only in the EXTDECS0 file. The SYSTEMENTRYPOINT_RISC_ procedure, which is defined only for native processes, returns either the 32-bit RISC address of the named entry point or, if not found, the value zero.
SYSTEMENTRYPOINTLABEL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Summary The SYSTEMENTRYPOINTLABEL procedure returns either the procedure label of the named entry point or, if not found, a zero.
15 Guardian Procedure Calls (T-V) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letters T through V. Table 45 lists all the procedures in this section.
TAKE^BREAK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Considerations Example Related Programming Manual Summary The TAKE^BREAK procedure enables BREAK monitoring for a file. The TAKE^BREAK procedure is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
Example CALL TAKE^BREAK ( OUT^FILE ); Related Programming Manual For programming information about the TAKE^BREAK procedure, see the Guardian Programmer's Guide.
TEXTTOSSID Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The TEXTTOSSID procedure scans a character string, expecting to find the external representation of a subsystem ID starting in the first byte (no leading spaces accepted). It returns the internal representation of the subsystem ID it finds.
(1,x) Error allocating private segment; x is the ALLOCATESEGMENT error code. (2,x) Problem opening the template file: x: >0 file-system error code -1 file code not 839 or 844 -2 file not disk file -3 file not key-sequenced -4 file has wrong record size -5 file has wrong primary key definition (3,x) Error reading the template file; x is the file-system error code. (4,0) Syntax error on the external form subsystem ID.
TIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Related Programming Manual Summary The TIME procedure provides the current date and time in integer form. Syntax for C Programmers #include void TIME ( short _near *date-and-time ); Syntax for TAL Programmers CALL TIME ( date-and-time ); ! o Parameter date-and-time output INT:ref:7 returns an array with the current date and time in this form: date-and-time [0] year (1983, 1984, ...
TIMER_START_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The TIMER_START_ procedure sets a timer to a given number of units of elapsed time, as measured by the processor clock. When the time expires, the calling process receives an indication in the form of a system message on $RECEIVE. TIMER_START_ measures the timeout value in microseconds.
param2 input INT(64):value is part of the timeout message read from $RECEIVE. TLEid output INT(32) .EXT:ref:1 is the identifier associated with the timer. TLEid should only be used to call the TIMER_STOP_ procedure. Returned Value INT(32) Outcome of the call: 0 The call is successful and the time has been started. 590 The parameter values are invalid or inconsistent. 3600 TIMER_START_ cannot allocate a TLE. This error occurs when all available TLEs are used.
TIMER_STOP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Summary The TIMER_STOP_ procedure stops a timer started using the TIMER_START_ procedure. When called this procedure ensures that: • the TLEid is valid • the TLE owner is referred by the same TLEid • the process that calls TIMER_STOP_ is the owner of the TLE NOTE: The TIMER_STOP_ procedure is supported only in H-series and J-series RVUs.
TIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Considerations Example Related Programming Manual Summary The TIMESTAMP procedure provides the internal form of the processor interval clock where the application is running.
local civil time. There is no way to examine a Julian timestamp and determine which of the three times it represents. Procedures that work with the 64-bit Julian timestamp are COMPUTETIMESTAMP, CONVERTTIMESTAMP, INTERPRETTIMESTAMP, JULIANTIMESTAMP, and SYSTEMCLOCK_SET_/SETSYSTEMCLOCK. • Process creation time is initialized by calling TIMESTAMP, which returns the local civil time in centiseconds (0.01 second = 10 milliseconds) since midnight (00:00) on 31 December 1974, in an array of three words.
TOSVERSION Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Example Summary The TOSVERSION procedure identifies the version of the operating system that is running. Syntax for C Programmers #include short TOSVERSION ( void ); Syntax for TAL Programmers version := TOSVERSION; Returned Value INT Version of the operating system in the form: <0:7> Uppercase ASCII letter indicating the version of the operating system.
TS_NANOSECS_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary The TS_NANOSECS_ procedure returns a value that represents the time (in nanoseconds) since the last coldload. Because this procedure measures time in such fine detail, it may take a little longer to obtain timestamp information. The header files for this procedure can be found in cextdecs for C/C++ programs and in extdecs0 for pTAL programs.
TS_UNIQUE_COMPARE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The TS_UNIQUE_COMPARE_ procedure compares two unique timestamps created using the TS_UNIQUE_CREATE_ Procedure (page 1431) and returns a value indicating their relationship. The header files for this procedure can be found in cextdecs for C/C++ programs and in extdecs0 for pTAL programs.
Returned Value INT(32) Result of the comparison. One of these values: 0 TS_LESS_THAN The value of ts1 is less than the value of ts2. This value is returned only if ts1 and ts2 are created on the same CPU. 1 TS_IDENTICAL The value of ts1 is identical to the value of ts2. This value is returned only if ts1 and ts2 are created on the same CPU. 2 TS_GREATER_THAN The value of ts1 is greater than the value of ts2. This value is returned only if ts1 and ts2 are created on the same CPU.
TS_UNIQUE_CONVERT_TO_JULIAN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary The TS_UNIQUE_CONVERT_TO_JULIAN_ procedure converts a unique timestamp into a Julian timestamp. The header files for this procedure can be found in cextdecs for C/C++ programs and in extdecs0 for pTAL programs. NOTE: The TS_UNIQUE_CONVERT_TO_JULIAN_ procedure is supported only in H-series and J-series RVUs.
TS_UNIQUE_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Returned Value Example Summary The TS_UNIQUE_CREATE_ procedure returns a 128-bit timestamp that is unique to the system it is generated on and any system in the same EXPAND network. The header files for this procedure can be found in cextdecs for C/C++ programs and in extdecs0 for pTAL programs.
Example STRUCT TIMESTAMP(NSK_UniqueTimeStamp128); ERR := TS_UNIQUE_CREATE_(TIMESTAMP); IF ERR THEN 1432 Guardian Procedure Calls (T-V)
UNLOCKFILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Example Related Programming Manual Summary The UNLOCKFILE procedure unlocks a disk file and any records in that file currently locked by the user. The "user" is defined either as the opener of the file (identified by filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
Parameters filenum input INT:value is a number of an open file that identifies the file to be unlocked. tag input INT(32):value is for nowait I/O only. tag is optional and the value you define uniquely identifies the operation associated with this UNLOCKFILE. NOTE: The system stores the tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed.
Related Programming Manual For programming information about the UNLOCKFILE procedure, see the Enscribe Programmer's Guide and the Guardian Programmer's Guide.
UNLOCKREC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Example Related Programming Manual Summary The UNLOCKREC procedure unlocks a record currently locked by the user. The "user" is defined either as the opener of the file (identified by filenum) if the file is not audited—or the transaction (identified by the TRANSID) if the file is audited.
Parameters filenum input INT:value is the number of an open file that identifies the file containing the record to be unlocked. tag input INT(32):value is for nowait I/O only. tag is optional and the value you define uniquely identifies the operation associated with this UNLOCKREC. NOTE: The system stores this tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed.
• File pointers after UNLOCKREC For unstructured files, the current-record pointer and the next-record pointer remain unchanged. • Transaction Management Facility (TMF) and UNLOCKREC A record that is locked in a file audited by TMF and has been modified by the current transaction is unlocked when an ABORTTRANSACTION or ENDTRANSACTION procedure is called for that file. Locks on modified records of audited files are released only when the transaction is ended or aborted by TMF.
UNPACKEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The UNPACKEDIT procedure converts a line image from EDIT packed line format into unpacked format. The input value is a text string in packed format, which includes blank compression codes; the returned value is the same text in unpacked format, which can include sequences of blank characters.
unpacked-line output STRING .EXT:ref:* is a string array that contains the line in unpacked format that is the outcome of the conversion. The length of the unpacked line is returned in the unpacked-length parameter. unpacked-limit input INT:value specifies the length in bytes of the string variable unpacked-line. unpacked-length output INT .EXT:ref:1 returns the actual length in bytes of the value returned in unpacked-line.
USER_AUTHENTICATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary The USER_AUTHENTICATE_ procedure verifies that a user exists and optionally logs on the user. This procedure should be called in a dialog mode to allow a dialog between the security mechanism and the application.
Syntax for TAL Programmers error := USER_AUTHENTICATE_ ( inputtext:inputtext–len ,[ options ] ,[ dialog-id ] ,[ status ] ,[ status-flags ] ,[ displaytext:displaytext-maxlen ] ,[ displaytext-len ] ,[ cmon-timeout ] ,[ termname:termname-len ] ,[ volsubvol:volsubvol-maxlen ] ,[ volsubvol-len ] ,[ initdir:initdir-maxlen ] ,[ initdir-len ] ,[ initprog:initprog-maxlen ] ,[ initprog-len ] ,[ initprog-type ] ,[ last-logon-time ] ,[ time-password-expires ] ); ,[ ipaddress:ipaddress-len ] ); ! ! ! ! ! ! ! ! ! ! ! !
<10> Send $CMON the Logon^msg message (-50). This bit is valid either when Safeguard software is running and configured with CMON ON or when Safeguard software is not running. <11> Do not allow the super ID to log on. <12> Do not allow a logon with a NonStop operating system user ID. When Safeguard software is running, the user can log on specifying either a member name or an alias. When Safeguard software is not running, the user can log on specifying a member name. <13> Require blind logon.
status Description 22 The password is about to expire, and the caller has sent the new password (oldpassword, newpassword, newpassword). USER_AUTHENTICATE_ successfully changes the password to newpassword. 23 Long password is specified when the PASSWORD-COMPATIBILITY-MODE is set to ON. First eight characters of the specified password are accepted as the new password. Values returned for error = 48 (security violation): status Description 1 User does not exist or password is incorrect.
status Description 11 Caller must set inputtext to a new password in the next call to USER_AUTHENTICATE_ to change the password, because the password has expired but the grace period is in effect. If the password is not changed, the user is not authenticated or logged on. 12 Caller must set inputtext to a new password in the next call to USER_AUTHENTICATE_ to verify the new password. status-flags output INT .EXT:ref:1 The bits, when set to 1, are defined as follows: <0:14> Reserved.
volsubvol:volsubvol-maxlen output:input STRING .EXT:ref:*, INT:value if present and if volsubvol-maxlen is not 0, returns the name of the default volume and subvolume inherited by the specified user when a logon session is initiated. This information is returned in external form. volsubvol-maxlen specifies the length of the string variable volsubvol in bytes. This parameter pair is required if volsubvol-len is specified. volsubvol-len output INT .
You must either specify all of these parameters or specify none of them: initprog:initprog-maxlen, initprog-len, and initprog-type. last-logon-time output FIXED .EXT:ref:1 returns the Julian timestamp of when the specified user last logged on. If the specified user has never logged on, 0F is returned. time-password-expires output FIXED .EXT:ref:1 returns the Julian timestamp of when the password of the specified user expires.
Considerations NOTE: An application should conduct a dialog with the security mechanism and determine the content of inputtext by the returned value of status when error is 70. The content of inputtext can change from RVU to RVU, so authentication in a single call to USER_AUTHENTICATE_ cannot be guaranteed. • Conducting a dialog A dialog allows the application to interact with the security mechanism. To initiate a dialog, set dialog-id to 0F and set inputtext to user name.
• Authenticating a user If authentication without logon is requested (options.<15> is 0), USER_AUTHENTICATE_ authenticates the user, but you cannot assume that user’s identity and you cannot log on. You must supply a password even if you do not request a logon unless: • ◦ You are the super ID (and options.<7> is not set to 1). ◦ You are the group manager (*,255) (and options.<7> is not set to 1). ◦ You are a user inquiring about yourself (and options.<7> is not set to 1).
The table below summarizes the functionalities: Bit 2 Bit 15 Functionality 1 1 Privlogon (logon without passwords) 1 0 Privlogon (authenticate-only with no delay imposed on supplying incorrect password when Safeguard is up) 0 1 Regular logon (password necessary for logon) 0 0 Regular authenticate-only (time delay imposed on failure of successive password verification attempts) ◦ If privlogon is requested through setting the options bit 2 and 15 to 1 when Safeguard software is running, and th
dialog-id = value of dialog-id returned from the previous call 3. Check error and status return values and enable echo with SETMODE function 20. • If error = 0 and status = 0, then the specified user is logged on. • If error = 0 and status = 8, then the specified user is logged on but the password is about to expire. The caller displays a message telling the user to change the password by the time-password-expires value. • If error = 0 and status = 22, then the specified user is logged on.
USER_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations OSS Considerations Example Summary The USER_GETINFO_ procedure returns the default attributes of the specified user. The user can be identified by user name, by user ID, or if Safeguard software is running, by alias.
Syntax for TAL Programmers error := USER_GETINFO_ ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ user-name:user-maxlen ] user-curlen ] user-id ] is-alias ] group-count ] group-list ] primary-group ] volsubvol:volsubvol-maxlen ] volsubvol-len ] initdir:initdir-maxlen ] initdir-len ] initprog:initprog-maxlen ] initprog-len ] default-security ] desc-field-text:desctxtfld-maxlen ] desctxt-len ] desc-field-bin:descbinfld-maxlen ] descbin-len ] ); ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! i,o:i i,o i,o o o o
On output, this parameter returns the user ID corresponding to the specified user-name. The user ID is a value in the range 0 through 65,535, where the low-order two bytes, that is, the third and fourth bytes from the left, identify the group and the member respectively. is-alias output INT .EXT:ref:1 indicates whether a user name or an alias is supplied in user-name. This parameter returns these values: -1 user-name is an alias. 0 user-name is a user name. group-count output INT .
initdir-maxlen specifies the length of the string variable initdir in bytes. This parameter pair is required if initdir-len is specified. initdir-len output INT .EXT:ref:1 if initdir is returned, contains its actual length in bytes. This parameter is required if initdir:initdir-maxlen is specified. initprog:initprog-maxlen output:input STRING .EXT:ref:*, INT:value if present and if initprog-maxlen is not 0, returns the OSS pathname for the initial program for the specified user in an OSS environment.
desc-field-text:desctxtfld-maxlen output:input STRING .EXT:ref:*, INT:value If present and when desctxtfld-maxlen is not zero, returns the contents of the textual description field of the specified user/alias. desctxt-len output INT .EXT:ref:* Returns the actual length of the specified user's textual description field. This parameter is required when desc-field-text:desctxtfld-maxlen is specified. desc-field-bin:descbinfld-maxlen output:input STRING .
OSS Considerations • The initdir parameter indicates the OSS pathname for the initial working directory for the specified user in an OSS environment. • The initprog parameter returns the OSS pathname for the initial program for the specified user in an OSS environment.
USER_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Example Summary The USER_GETNEXT_ procedure returns the next user name or alias in the order in which it is stored by the security mechanism in effect. On successive calls, all user names and aliases can be obtained.
is-alias input, output INT .EXT:ref:1 on input, indicates whether the user-name input parameter contains a user name or an alias. This parameter can be set to these values: 0 user-name is a user name. nonzero nonzerouser-name is an alias. On output, indicates whether the user-name output parameter contains a user name or an alias. This parameter returns these values: -1 user-name is an alias. 0 user-name is a user name.
error := USER_GETNEXT_ (search^name:32, search^len, is^alias); name^list[name^entry].name ‘:=‘ search^name FOR search^len BYTES; name^list[name^entry].len := search^len; name^entry := name^entry + 1; END; IF is^alias THEN BEGIN alias^entry := 0; search^len := 0; ! decrement name^entry, because it was an alias name^entry := name^entry - 1; WHILE (error <> 0) DO BEGIN error := USER_GETNEXT_ (search^name:32, search^len, is^alias); alias^list[alias^entry].
USERDEFAULTS Procedure (Superseded by USER_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support aliases or groups.
user-name input, output STRING .EXT:ref:16 specifies the user name for which the default information will be retrieved. Either user-id or user-name must be specified; if both are supplied, user-name returns the user name corresponding to user-id. The user-name is passed, and returned, in the form: [0:3] group name, blank-filled [4:7] member name, blank-filled The group name and member name must both be input in uppercase. volsubvol output STRING .
Condition Code Settings = (CCE) indicates that the default information is returned for the specified user. > (CCG) indicates that the specified user ID or user name is undefined. < (CCL) indicates that a required parameter is missing, that a buffer is out of bounds, or that an I/O error occurred on the user ID file ($SYSTEM.SYSTEM.USERID). Returned Value INT A file-system error code that indicates the outcome of the call. Common errors returned are: 0 No error.
USEREVENT... Procedures The USEREVENT... procedures operate on user events. User events are events that are defined by an application process to facilitate cooperation and coordination with other processes on the same CPU. One process defines and owns the event and can wait for the event to occur; other processes can cause that occurrence, subject to security considerations.
The consumer can wait on more than one event at a time (which is common), and the producer can cause more than one event to occur at a time (which is unusual). If the intersection of the wait set and the occurred-events set contains more than one event, the wait operation reports only the highest-priority event to the consumer, which must iterate to consume all the events. The paradigm by which the application causes and waits upon user events must be designed with care.
USEREVENT_AWAKE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The USEREVENT_AWAKE_ procedure is used by an application to awaken a target process on the same logical processor upon the occurrence of one or more application-defined user events. The call immediately awakens the target process if it is blocked inside of the USEREVENT_WAIT_ procedure or one of the AWAITIO/FILE_COMPLETE_ family of procedures and waiting on that event.
awakeMask input INT(32) specifies an event mask designating one or more user events to be placed in the occurred state in the target process. This mask is a bit mask of events such that the higher-order bit has the higher priority. The units bit is reserved and ignored. Returned Value INT(16) Outcome of the call: 0 Success in awakening the target process. 14 The specified targetProcessPhandle refers to an invalid or non-existent process. 22 Address specified for targetProcessPhandle is out of bounds.
USEREVENT_GET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Returned Value Considerations Summary The USEREVENT_GET_ procedure is used by an application to get the current set of application-defined user events in this process, as specified by USEREVENT_SET_. USEREVENT_GET_ returns the current set of user events in the return value. NOTE: The USEREVENT_GET_ procedure is supported on systems running H06.27 and later H-series RVUs and J06.16 and later J-series RVUs.
USEREVENT_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The USEREVENT_SET_ procedure defines the set of user events upon which an application intends to wait, using the common wait and I/O completion procedures. USEREVENT_SET_ defines the set of user events without waiting or checking these events; the process can subsequently use the AWAITIO/FILE_COMPLETE_ family of procedures to wait on these events.
options input INT determines whether the provided waitMask is logically ORed into the process’ existing wait mask or replaced with the existing mask. If a value other than 0 or 1 is specified, an error is returned. 0 Replace existing process wait mask. 1 Logically OR the provided waitMask to the process’ existing wait mask. Returned Value INT(16) Outcome of the call: 0 Success in setting the application-defined user events for the process.
USEREVENT_WAIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The USEREVENT_WAIT_ procedure waits for one or more of 31 application-defined user events to occur within a specified time. USEREVENT_WAIT_ is used by applications that want to use user events to coordinate their internal operations but does not mix these wait operations with the common wait and I/O completion procedures.
timeout input INT(64) specifies the time, in microseconds, to wait for the user event. Valid timeout ranges: <0 Call waits indefinitely until one of the events in waitMask occurs. The call never returns if none of the user events occur. >0 Process will wait for specified duration; see Considerations. 0 Call returns immediately with a valid event if already occurred or with 1. Returned Value INT(32) A bit mask containing a single bit indicating the result of the wait.
USEREVENTFILE_REGISTER_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary The USEREVENTFILE_REGISTER_ procedure is used to establish a file number to access an application-defined user event set for an application that intends to use user events in combination with the common wait and I/O completion procedures. You can use the returned file number later as an input to the AWAITIO/FILE_COMPLETE_ family of procedures.
Parameters userEventFilenum output INT .EXT:ref:1 on successful return, contains the file number to be passed to one of the AWAITIO/FILE_COMPLETE_ family of procedures to wait for user events. This value is only valid if the error returned value is 0. errorDetail output INT .EXT:ref:1 specifies the file-system error obtained while registering the file: 31 Unable to obtain file-system buffer space. 34 Unable to obtain a file-system control block.
USERIDTOUSERNAME Procedure (Superseded by USER_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support aliases or groups. The USERIDTOUSERNAME procedure returns the user name, from the file $SYSTEM.SYSTEM.USERID, that is associated with a designated user ID.
Condition Code Settings = (CCE) indicates that id-name is out of bounds or that an I/O error occurred with the $SYSTEM.SYSTEM.USERID file. > (CCG) indicates that the designated user name returned. < (CCL) indicates that the specified user ID is undefined.
USERIOBUFFER_ALLOW_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Considerations Summary The USERIOBUFFER_ALLOW_ procedure dynamically sets the process behavior to be the same as if the objectfile flag "allow_user_buffers" were set in eld, provided it is called before opening any files. Its impact is limited to files opened by FILE_OPEN_ after the procedure is called. It has no impact on I/O operations initiated on files opened before the call or files opened by OPEN.
USERNAMETOUSERID Procedure (Superseded by USER_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support aliases or groups. The USERNAMETOUSERID procedure returns the user ID, from the file $SYSTEM.SYSTEM.USERID, that is associated with a designated user name.
Condition Code Settings = (CCE) indicates that name-id is out of bounds or that an I/O error occurred with the $SYSTEM.SYSTEM.USERID file. > (CCG) indicates that the designated user ID returned. < (CCL) indicates that the specified user ID is undefined.
USESEGMENT Procedure (Superseded by SEGMENT_USE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Condition Code Settings Returned Value Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. The USESEGMENT procedure selects a particular extended data segment to be currently addressable by the calling process.
Condition Code Settings < (CCL) indicates that segment-id is not allocated, or that the segment cannot be used by a nonprivileged caller. = (CCE) indicates that the operation is successful. > (CCG) does not return from USESEGMENT. Returned Value INT Segment ID of the previously used selectable segment, if any; otherwise, -1. If segment-id specifies a flat segment, old-segment-id returns the segment ID of the current in-use selectable segment.
VERIFYUSER Procedure (Superseded by USER_AUTHENTICATE_ Procedure and USER_GETINFO_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Example Summary NOTE: This procedure is supported for compatibility with previous software and should not be used for new development. This procedure does not support aliases or groups. The VERIFYUSER procedure has three different functions.
or [0] .<0:7> group ID [0] .<8:15> member ID [1:7] zeros (ASCII nulls) In either case: [8:11] password, blank-filled (see Considerations) logon input INT:value if present, has this meaning: 0 verify user but do not log on <> 0 verify user and log on if omitted, is assumed to have a value of 0. default output INT:ref:18 if present, returns information regarding the user specified in user-name-or-id: [0:3] group name, blank-filled [4:7] member name, blank-filled [8] .<0:7> group ID .
default-len input INT:value is the length, in bytes, of the default array. default-len is required if default is specified. This number must always be specified as 36; in the future, new fields can be added to default, requiring default-len to become larger. Condition Code Settings < (CCL) indicates that a buffer is out of bounds, or that an I/O error occurred on the user ID file ($SYSTEM.SYSTEM.USERID). = (CCE) indicates a successful verification or logon.
Example USER := 3 '<' 8 + 17; USER[1] ':=' 0 & USER[1] FOR 6; USER[8] ':=' password FOR 8; LOGON := 1; ! user ID 3,17. ! all zeros. ! log this user on. CALL VERIFYUSER ( USER , LOGON , DEFAULT , DEFAULT^LEN ); IF < THEN ... ! buffer or I/O error, ELSE IF > THEN .. . ! no such user, or bad ! password. ELSE ... ! successful. . The array "USER" is prepared with the member and group ID and then passed to VERIFYUSER. VERIFYUSER logs on the process with the member ID 17 and group ID 3.
VRO_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Summary The VRO_SET_ procedure causes a voluntary rendezvous opportunity to take place. NOTE: The VRO_SET_ procedure is supported only in H-series and J-series RVUs.
16 Guardian Procedure Calls (W-Z) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letters W through Z. Table 46 lists all the procedures in this section.
WAIT^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The WAIT^FILE procedure is used to wait or check for the completion of an outstanding I/O operation. WAIT^FILE is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
time-limit input INT(32):value if present, indicates whether the caller waits for completion or checks for completion. If omitted, the time limit is set to -1D. Possible values are: <> 0D indicates a wait for completion. The time limit then specifies the maximum time, in 0.01-second units, the caller waits for a completion. 0D indicates a check for completion. WAIT^FILE immediately returns to the caller regardless of whether there is a completion.
WRITE[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Interprocess Communication Considerations Considerations for WRITEX Only Errors for WRITE[X] Errors for WRITEX Only Example Related Programming Manuals Summary The WRITE[X] procedures write data from an array in the application program to an open file (see Considerations (page 1492)).
• CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int. • The function value returned by WRITE[X], which indicates the condition code, can be interpreted by _status_lt(), _status_eq(), or _status_gt() (defined in the file tal.h).
tag input INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this WRITE[X]. NOTE: The system stores this tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed. If WRITEX is used, you must call AWAITIOX to complete the I/O. If WRITE is used, you can use either AWAITIO or AWAITIOX to complete the I/O.
On NSAA systems, data being read or written may be stored in the 32MB process file segment (PFS) along with the open file information. This segment provides an upper limit on the number of concurrent no-wait I/O operations with large read-count or write-count values for those applications with a large number of open files. You can work around this limitation by following these guidelines in your application: 1. Define read and write buffers with sizes that are multiples of 16 KB. 2.
If the file is audited, the record is available for read operations when the transaction associated with the write operation commits. If the transaction aborts, the record is never available to read operations. If the file is not audited, the record is available as soon as the write operation finishes successfully. Unlike other key-sequenced files, a write operation to a queue file will never encounters an error 10 (duplicate record) because all queue file records have unique keys generated for them.
DP2 performance with unstructured files is best when requested transfers begin on BUFFERSIZE boundaries and are integral multiples of BUFFERSIZE. ◦ If the WRITE[X] is to an unstructured disk file, data is transferred to the record location specified by the next-record pointer. The next-record pointer is updated to point to the record following the record written.
Errors for WRITE[X] The WRITE[X] procedure returns FEFILEFULL (45) when passed a filenum for an unstructured open of the primary partition of an enhanced key-sequenced file. For more information on enhanced key-sequenced files, see the Enscribe Programmer's Guide.
WRITE^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The WRITE^FILE procedure writes a file sequentially. The file must be open with write or read/write access. WRITE^FILE is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
reply-error-code input INT:value (for $RECEIVE file only) if present, is a file-system error to return to the requesting process by REPLY. If omitted, 0 is returned. forms-control-code input INT:value (optional) indicates a forms-control operation to be performed before executing the actual WRITE when the file is a process or a line printer. The forms-control parameter corresponds to parameter of the file-system CONTROL procedure for operation equal to 1.
WRITEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The WRITEEDIT procedure accepts a line in unpacked format, converts it into EDIT packed line format, and writes it to the specified file. WRITEEDIT is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
record-number input INT(32):value if present, specifies the record number of the line to be written. If record-number: • is greater than or equal to 0, it specifies 1000 times the EDIT line number of the line to be written. • is -1, the line is written at the beginning of the file. • is -2, the line is written at the end of the file. • is -3, the line is written to the line represented by the file's current record number. If this parameter is omitted, -3 is used. unpacked-line input STRING .
Example INT(32) record^num := -2D; ! write to end of file . . error := WRITEEDIT ( filenumber, record^num, line^image, line^length ); Related Programming Manual For programming information about the WRITEEDIT procedure, see the Guardian Programmer's Guide.
WRITEEDITP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Example Related Programming Manual Summary The WRITEEDITP procedure accepts a line in EDIT packed line format and writes it to the specified file. WRITEEDITP is an IOEdit procedure and can only be used with files that have been opened by OPENEDIT or OPENEDIT_.
• is -2, the line is written at the end of the file. • is -3 or omitted, the line is written to the line represented by the file's current record number. packed-line input STRING .EXT:ref:* is a string array that contains the line in packed format that is to be written. The length of packed-line is specified by the packed-length parameter. packed-length input INT:value specifies the length in bytes of packed-line. The packed-length must be in the range 1 through 256.
WRITEREAD[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Considerations for WRITEREADX Only Errors for WRITEREADX Only Example Related Programming Manuals Summary The WRITEREAD[X] procedures write data to a file from an array in the application process, then wait for data to be transferred back from the file. The data from the read portion returns in the same array used for the write portion.
Syntax for C Programmers #include _cc_status WRITEREAD ( short filenum ,short _near *buffer ,unsigned short write-count ,unsigned short read-count ,[ unsigned short _near *count-read ] ,[ __int32_t tag ] ); #include _cc_status WRITEREADX ( short filenum ,char _far *buffer ,unsigned short write-count ,unsigned short read-count ,[ unsigned short _far *count-read ] ,[ __int32_t tag ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the t
write-count input INT:value is the number of bytes to be written: {0:32755} for terminals {0:57344} for interprocess files NOTE: When using terminals in block mode, an error 21 occurs if write-count exceeds 256 bytes. read-count input INT:value returns the number of bytes to be read: {0:32755} for terminals {0:57344} for interprocess files count-read output INT:ref:1 (for WRITEREAD) INT .EXT:ref:1 (for WRITEREADX) is for wait I/O only.
Considerations • Waited I/O READ If a waited I/O WRITEREAD[X] is executed, the count-read parameter indicates the number of bytes actually read. • Nowait I/O READ If a nowait I/O WRITEREAD[X] is executed, count-read has no meaning and can be omitted. The count of the number of bytes read is obtained when the I/O operation completes through the count-transferred parameter of the AWAITIO[X] procedure.
Errors for WRITEREADX Only In addition to the errors currently returned from the WRITEREAD procedure, file-system error 22 is returned when: • The address of a parameter refers to the selectable segment area but no selectable segment is in use at the time of the call. • The address of a parameter is extended, but it is an absolute address and the caller is not privileged. • The file system cannot use the user's segment when needed.
WRITEUPDATE[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Magnetic Tape Considerations Considerations for WRITEUPDATEX Only Errors for WRITEUPDATEX Only Example Related Programming Manuals Summary The WRITEUPDATE[X] procedures transfer data from an array in the application program to a file.
Syntax for C Programmers #include _cc_status WRITEUPDATE ( short filenum ,short _near *buffer ,unsigned short write-count ,[ unsigned short _near *count-written ] ,[ __int32_t tag ] ); #include _cc_status WRITEUPDATEX ( short filenum ,const char *buffer ,unsigned short write-count ,[ unsigned short _far *count-written ] ,[ __int32_t tag ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS
For key-sequenced and relative files: 0 means delete the record. For entry-sequenced files: 0 means anything <> the record's length is invalid. count-written output INT:ref:1 (for WRITEUPDATE) INT .EXT:ref:1 (for WRITEUPDATEX) is for wait I/O only. It returns a count of the number of bytes written to the file. tag input INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this WRITEUPDATE[X].
• Waited WRITEUPDATE[X] If a waited WRITEUPDATE[X] is executed, the count-written parameter indicates the number of bytes actually written. • Nowait WRITEUPDATE[X] If a nowait WRITEUPDATE[X] is executed, count-written has no meaning and can be omitted. The count of the number of bytes written is obtained through the count-transferred parameter of the AWAITIO[X] procedure when the I/O completes.
Disk File Considerations • Large data transfers For WRITEUPDATEX only, large data transfers (more than 4096 bytes), can be enabled by using SETMODE function 141. See Table 44 (page 1319). • Random processing and WRITEUPDATE[X] For key-sequenced, relative, and entry-sequenced files, random processing implies that a designated record must exist. This means that positioning for WRITEUPDATE[X] is always to the record described by the exact value of the current key and current-key specifier.
◦ Changing the primary-key of a key-sequenced record An update to a record in a key-sequenced file cannot alter the value of the primary-key field. Changing the primary-key field must be done by deleting the old record (WRITEUPDATE[X] with write-count = 0) and inserting a new record with the key field changed (WRITE). ◦ Current-state indicators after WRITEUPDATE[X] After a successful WRITEUPDATE[X], the current-state indicators remain unchanged.
• Nowait I/O initiated with these routines may be canceled with a call to CANCEL or CANCELREQ. The I/O is canceled if the file is closed before the I/O completes or AWAITIOX is called with a positive time limit and specific file number and the request times out. • If the extended address of the buffer is odd, bounds checking rounds the address to the next lower word boundary and checks an extra byte as well. The odd address is used for the transfer.
WRITEUPDATEUNLOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Considerations for WRITEUPDATEUNLOCKX Only Errors for WRITEUPDATEUNLOCKX Only Example Related Programming Manuals Summary The WRITEUPDATEUNLOCK[X] procedures perform random processing of records in a disk file.
#include _cc_status WRITEUPDATEUNLOCKX ( short filenum ,const char _far *buffer ,unsigned short write-count ,[ unsigned short _far *count-written ] ,[ __int32_t tag ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t, which for TNS and TNS/R compiles is defined as long and for TNS/E compiles is defined as int.
tag input INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this WRITEUPDATEUNLOCK[X]. NOTE: The system stores this tag value until the I/O operation completes. The system then returns the tag information to the program in the tag parameter of the call to AWAITIO[X], thus indicating that the operation completed. If WRITEUPDATEUNLOCKX is used, you must call AWAITIOX to complete the I/O.
or READUPDATE[X]. The current-record and next-record pointers are not changed by a call to WRITEUPDATEUNLOCK[X]. • How WRITEUPDATEUNLOCK[X] works The record unlocking performed by WRITEUPDATEUNLOCK[X] functions in the same manner as UNLOCKREC. • Record does not exist Positioning for WRITEUPDATEUNLOCK[X] is always to the record described by the exact value of the current key and current-key specifier.
• If the file is opened for nowait I/O, you must not modify the buffer before the I/O completes with a call to AWAITIOX. This also applies to other processes that may be sharing the segment. It is the application's responsibility to ensure this. • If the file is opened for nowait I/O, and the I/O has been initiated with these routines, the I/O must be completed with a call to AWAITIOX (not AWAITIO).
XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK[64]_ Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The XBNDSTEST procedure aids user programs in checking stack limits or parameter addresses. (LASTADDRX provides a similar function.
flags input INT:value is defined as: <0:12> Must be zero. <13> Use extended address limits from constants. <14> Parameter must be word-aligned. <15> Skip the bounds test and return 0. constants input FIXED:value is a set of constant values generated by XSTACKTEST. Returned Value INT One of these values: 1 In bounds, but in a read-only segment or (on native systems only) in the system library. 0 In bounds and writable. -1 Out of bounds or invalid address.
XSTACKTEST Procedure (Superseded by HEADROOM_ENSURE_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Returned Value Considerations Summary NOTE: This procedure cannot be called by native processes. Although this procedure is supported for TNS processes, it should not be used for new development. The XSTACKTEST procedure, used with LASTADDRX and XBNDSTEST procedures, checks stack limits.
flags input INT:value is defined as: <0:13> Must be zero. <14> Allow parameters that use privileged addresses. <15> Skip the stack test and return 0. constants output FIXED:ref:1 is a returned set of constant values that may be used when calling XBNDSTEST. Returned Value INT One of these file-system error numbers: 0 Adequate stack space available. 2 Undefined flags value. 21 stackwords is less than 1. 22 Bounds error on firstparm or constants. 632 Insufficient stack space available.
A Device Types and Subtypes Table 47 Device Types and Subtypes Type Device Subtype Descriptions 0 Process 0 Default subtype for general use 1-49 Reserved for definition by HP. These subtypes are defined: 1 = CMI process 2 = Security monitor process 30 = Device simulation process 31 = Spooler collector process 48 = TFTP server process 49 = SNMP trap multiplexor 1 Operator console 50-63 For general use 0 $0 (operator process) or alternate collector 1 $0.
Table 47 Device Types and Subtypes (continued) Type Device Subtype Descriptions 36 NonStop™ Storage Management Foundation (SMF) virtual disk process 38 4560 (2 GB formatted capacity per spindle) with ServerNet/DA 39 4570 (4 GB) with ServerNet DA 41 4604 (4 GB) 42 4608 (8 GB) 4609 (8 GB) 4 Magnetic tape unit 43 4618 (18 GB) 43 4619 (18 GB) (15,000 rpm) 44 4636 (36 GB) 4637 (36 GB) 45 4672 (72 GB) 46 46144 (144 GB) SCSI disk for an S-series system 48 4590 (18 GB) with ServerNet/DA
Table 47 Device Types and Subtypes (continued) Type Device Subtype Descriptions 6 7 8 9 10 32 6 Terminal 0 Conversational mode (P/N 6401/6402) or PATPTERM (non-HP) device 1 Page mode (P/N 6511, 6512) 2 Page mode (P/N 6520, 6524) 3 N.A. 4 Page mode (P/N 6526, 6528, 653x) 5 N.A.
Table 47 Device Types and Subtypes (continued) Type Device Subtype Descriptions 11 Burroughs, point-to-point, contention 13 Burroughs, point-to-point, contention 30 Full duplex (FDX), out line 31 Full duplex (FDX), in line 32 NASDAQ, Full duplex (FDX), out line 33 NASDAQ, Full duplex (FDX), in line 40 Asynchronous line supervisor 50 N.A. 56 N.A.
Table 47 Device Types and Subtypes (continued) Type Device Subtype Descriptions 24 OSS 25 SMF pool 0 26 Tandem HyperLink (THL) 0 27 IPBMON 0 Interprocessor bus monitor for Fiber Optic Extension (FOX) or TorusNet vertical subsystem in FOX-compatibility mode 5 $IPB1 (TorusNet vertical subsystem master service manager in multiple-link mode) 6 Service manager for additional TorusNet vertical links Open System Services Storage pool process 28 $ZNUP 0 Network Utility Process 29 $ZMIOP 1
Table 47 Device Types and Subtypes (continued) Type Device Subtype Descriptions 2 ADCCP line 3 N.A.
Table 47 Device Types and Subtypes (continued) Type 61 Device Subtype TR3271 1 X.25 Descriptions 11 Line attached to SWAN concentrator 0-61 N.A. 62 N.A. 63 Line attached to SWAN concentrator 62 Expand NCP 6 $NCP Network Control Process 63 Expand Line Handler 0 Single-line handler over X.25, SNA, IP, ATM 1 Multiline path handler 2 Multiline line handler over X.
B Reserved Process Names This appendix contains the names that should be avoided when choosing process names. The names listed here are reserved for HP use: $AOPR $CMON $CMP $C9341 $DMnn $IMON $IPB $KEYS $MLOK $NCP $NULL $OSP $PM $S $SIMnn $SPLS $SSCP $SYSTEM $T $TICS $TMP $Xname $Yname $Zname nn is any two digits (00 through 99) name is any combination of 1 through 4 letters or digits (A through Z, 0 through 9).
C Completion Codes This appendix lists the completion codes returned after execution of a process or, in some instances, a job step. These codes indicate the degree of success of a program in a standard manner, thus making it possible to create or build further steps based on these codes. Completion codes -32768 through -1 are reserved for HP use. The caller must be privileged to have a negative completion code returned to its ancestor.
These completion codes are reserved for HP use: Completion Code Definition -1 A trap was detected in a Guardian TNS process. If the system detects the absence of a trap handler routine or encounters another trap in a trap handler, then in addition to an abnormal termination, this completion code is returned automatically in the process deletion (ABEND) message. The contents of the text string vary with the state of the process.
-10 An OSS process or native process terminated because it was unable to obtain resources for signal delivery. The termination information field of the message contains the signal number. -11 An OSS process or native process terminated because it attempted to resume from a nonresumable signal. The termination information field of the message contains the signal number. -12 One of the functions in the OSS exec or tdm_exec set of functions executed successfully.
D File Names and Process Identifiers This appendix summarizes the syntax for file names and process identifiers. It is in four principal subsections. The first subsection specifies reserved file names. The second subsection describes the syntax that HP recommends for all new development. Any system procedure that has a name ending with an underscore (_) expects this syntax when you specify a file name or a process identifier as a parameter.
file-id specifies the file identifier (or name) of a permanent disk file. A permanent-file identifier has one to eight alphanumeric characters; the first character must be a letter. temp-file-id specifies the file identifier (or name) of a temporary disk file. A temporary-file identifier consists of a pound sign (#) followed by four to seven numeric characters. The operating system assigns file identifiers to temporary files. Example This is an example of a fully qualified disk file name: \hdq.$mkt.
node specifies the name of the node on which the process is running. A node name consists of a backslash (\) followed by one to seven alphanumeric characters; the first alphanumeric character must be a letter. cpu specifies the processor number of the processor in which the process is running. cpu is one or two digits representing a value in the range 0 through 15. A leading zero must be suppressed. A colon (:) separates the dollar sign ($) from cpu.
Process Descriptors A process descriptor is a form of process file name that always includes the node and seq-no sections of the name; when identifying a named process, it never includes the optional qualifiers qual-1 or qual-2. Guardian 90 procedures always return a process descriptor as the external-form representation of a process or process pair. Examples These are examples of process descriptors: ode5.$zproc:1622091078 \east.
Process Handles A process handle is a ten-word structure that identifies a single named or unnamed process. CAUTION: The format of a process handle is defined by HP and is subject to change in future RVUs. Applications should not try to extract information (such as processor or PIN) from a process handle except by using a system procedure such as PROCESSHANDLE_DECOMPOSE_. A process handle contains this information about a process: • The PIN, which identifies the process within a processor.
volume specifies the name of the volume on which the file resides. A volume name consists of a dollar sign ($) followed by one to seven alphanumeric characters (one to six if you also specify system); the first alphanumeric character must be a letter. subvol specifies the name of the subvolume on which the file resides. A subvolume name has one to eight alphanumeric characters; the first character must be a letter. file-id specifies the file identifier (or name) of a permanent disk file.
Examples These are examples of external nondisk file names: \sw.$proc.#out.default \sw.$drvr.#term $s.#lp $tape4 $10 Internal File Names An internal file name is a 12-word array in which the different file name parts begin at fixed locations in the array. The internal form of a file name is typically used within the system, as when a file name is passed between an application process and the operating system.
Process File Names A process file name is a 12-word array that uniquely identifies a process. There are three forms of the process file name: the timestamp form, local name form, and network form. Note that these forms cannot be used to designate a process that has a PIN greater than 255. Timestamp Form of Process File Name The timestamp form of the process file name is: [0].<0:1> 2 [0].<2:7> Reserved [0].<8:15> System number (0 through 254) [1:2] Low-order 32 bits of creation timestamp [3].
OSS Pathname Syntax OSS pathnames can be up to PATH_MAX characters long, including a null termination character. PATH_MAX is a symbolic constant defined in the limits.h header file. The syntax for an OSS pathname is: [[/][directory/]...]filename / specifies the root directory when it appears at the beginning of a pathname. Otherwise, it separates directory names and filenames. directory specifies the name of a directory. All characters are valid except slash (/) and the ASCII NULL character.
/E/forty/usr/ccom/prog1.c Refers to an OSS file name (prog1.c) in a subdirectory (ccom) in a subdirectory (usr) in a subdirectory (forty) after the E root directory. /E/forty/G/books/donl/text180 Refers to a Guardian file name (text180) in a subvolume (donl) in a volume (books) on the HP node (forty).
E DEFINEs This appendix describes DEFINEs and the attributes of the different classes of DEFINEs. For information about using DEFINEs programmatically, see the Guardian Programmer's Guide. For information about using DEFINEs interactively with a TACL process, see the Guardian User's Guide. What Is a DEFINE? A DEFINE is a named set of attributes and associated values. In a DEFINE (as with an ASSIGN command) you can specify information that is to be communicated to processes you start.
Attribute Data Types When you assign a value to an attribute, you specify the value as a parameter to a procedure call. This parameter must be declared type STRING. The string values that you can specify for a particular DEFINE attribute is determined by the data type of the DEFINE attribute. The available attribute data types are: String The attribute can contain a string of from 1 to a maximum of 512 ASCII characters, depending on the particular attribute.
CLASS SEARCH DEFINEs A CLASS SEARCH DEFINE contains information to be used for resolving file names with a search list. A CLASS SEARCH DEFINE has 21 attributes named SUBVOL0 through SUBVOL20 and another 21 attributes named RELSUBVOL0 through RELSUBVOL20. Each of these attributes takes the same form and is optional. The value of one attribute is either a single subvolume specification or a list of them enclosed in parentheses and separated by commas.
One CLASS TAPECATALOG DEFINE must be used for each labeled tape file that you want to read or write. CLASS TAPECATALOG DEFINEs are processed by the FILE_OPEN_ and OPEN procedures. The DSM/TC facility automatically selects tape volumes and catalogs the files written to tape by applications using CLASS TAPECATALOG DEFINEs. For detailed information about the CLASS TAPECATALOG DEFINEs and their attributes, see the DSM/Tape Catalog User's Guide.
F Formatter Edit Descriptors This appendix describes edit descriptors, which are specified as input values to the FORMATCONVERT procedure. Edit descriptors are of two types: those that specify the conversion of data values (repeatable) and those that do not (nonrepeatable). The effect of repeatable edit descriptors can be altered through the use of modifiers or decorations, which are enclosed in brackets ([ ]), preceding the edit descriptors to which they refer.
Summary of Repeatable Edit Descriptors Repeatable edit descriptors direct the formatter to obtain the next data list element and perform a conversion between internal and external representation. They can be preceded by modifiers or decorations that alter the interpretation of the basic edit descriptor. Modifiers and decorations apply only to output conversion. They are allowed but ignored for input.
Nonrepeatable Edit Descriptors These descriptions show the form, function, and requirements for each of the nonrepeatable edit descriptors. Tabulation Descriptors The tabulation descriptors specify the position at which the next character is transmitted to or from the buffer. This allows portions of a buffer to be processed in an order other than strictly left to right, and permits processing of the same portion of a buffer more than once.
Literal Descriptors Literal descriptors are alphanumeric strings in either form: OR dc c c ... c d 1 2 3 n nHc c c ... c 1 2 3 n d either an apostrophe (') or a quotation mark ("); the same character must be used for both the opening and closing delimiters c any ASCII character n an unsigned nonzero integer constant specifying the number of characters in the string; n cannot exceed 255 On input, a literal descriptor is treated as nX.
Optional Plus Descriptors (S, SP, SS) Optional plus descriptors can be used to control whether optional plus characters appear in numeric output fields. In the absence of explicit control, the formatter does not produce any optional plus characters. The forms of the optional plus descriptors are: S SP SS These descriptors have no effect upon input. If the S descriptor is encountered in the format, the formatter does not produce a plus in any subsequent position that normally contains an optional plus.
Examples This group of edit descriptors is preceded by a repeat factor that specifies the formatting of ten data items, each one to be preceded by the label NUMBER. If there are fewer than ten data items in the data list, formatting terminates immediately after the last value is processed. If the colon is not present, formatting continues until the I edit descriptor is encountered for the fourth time. This means the fourth label is added before the formatting is terminated.
the data element and the external field unless an RJ modifier is affecting the descriptor, in which case the transferring of characters begins with the right character of each. 2. If w is less than the number of characters in the data element, the field overflow condition is set. 3. If w is greater than the number of characters in the data element, the remaining characters in the external field are filled with spaces (unless another fill character is specified by the FL modifier).
The B Edit Descriptor The binary edit descriptor is used to display or interpret data values in binary (base 2) integer form. The B edit descriptor has these forms: Bw OR Bw.m w is an unsigned integer constant that defines the total field width and cannot exceed 255. The field processed is the w characters starting at the current position. After the field is processed, the current position is advanced by w characters.
precision of the internal representation are ignored. The basic form can be followed by an exponent in one of these forms: • Signed integer constant • E followed by zero or more blanks, followed by an optionally signed integer constant • D followed by zero or more blanks, followed by an optionally signed integer constant An exponent containing a D is processed identically to an exponent containing an E. On output, the field (for a scale factor of zero) appears in this form: {[+]} [0].
These examples illustrate input: External Field Format Data Element Value | 0.100E+03| E12.3 100 | 100.05 | E12.5 100.05 12345| E12.3 12.345 | The "|" character is used to denote the boundaries of the output field. The F Edit Descriptor The fixed-format edit descriptor is used to display or interpret data in fixed point form. The F edit descriptor has these forms: Fw OR Fw.d.m w an unsigned integer constant that defines the total field width and cannot exceed 255.
On input, the G edit descriptor is the same as the E edit descriptor. The method of representation in the output field depends on the magnitude of the data being processed, as follows: Magnitude of Data Not Less Than Less Than Equivalent Conversion Effected 0.1 Ew.d or Ew.dEe 0.1 1.0 F(w-n).d,n(' ') 1.0 10.0 F(w-n).(d-1),n(' ') 10.0 100.0 F(w-n).(d-2),n(' ') . . . . . . . . . 10 ** (d-2) 10 ** (d-1) F(w-n).1,n(' ') 10 ** (d-1) 10 ** d F(w-n.0,n(' ') 10 ** d Ew.d or Ew.
m an unsigned integer constant that defines the number of digits that must be present on output b an unsigned integer constant that defines the number base of the external data and cannot be less than 2 or greater than 16.
The L Edit Descriptor The logical edit descriptor is used to display or interpret data in logical form. The L edit descriptor has the form: Lw w an unsigned integer constant that defines the total field width and cannot exceed 255. The field processed is the w characters starting at the current position. After the field is processed, the current position is advanced by w characters.
V Decimal alignment character . Decimal alignment character The field width w is determined by the number of characters, including spaces but excluding Vs, between the mask delimiters. The field processed is w characters starting at the current position. After the field is processed, the current position is advanced by w characters. Except for the decimal point alignment character, V, each character in the mask either defines a character position in the field or is directly inserted in the field.
Format Two: M<$ 999,999,999 AND NO CENTS> Format One Format Two $ 298,738,472 AND NO CENTS $ 298,738,472 AND NO CENTS $ 389,488 AND NO CENTS $ 000,389,488 AND NO CENTS $ 666 AND NO CENTS $ 000,000,666 AND NO CENTS $ 0 AND NO CENTS $ 000,000,000 AND NO CENTS The M edit descriptor can be useful in producing visually effective reports, by formatting values into patterns that are meaningful in terms of the data they represent.
The Z Edit Descriptor The Z edit descriptor is used to display or interpret data values in hexadecimal (base 16) integer form. The Z edit descriptor has these forms: Zw OR Zw.m w an unsigned integer constant that defines the total field width and cannot exceed 255. The field processed is the w characters starting at the current position.
The fill-character modifier has the form: FL char char any single character, enclosed in quotation marks or apostrophes. These are examples of fill-character replacement: Format Data Value Result [FL'.']A10 'THEN' |THEN......| [RJ,FL">"]A7 'HERE' |> >>HERE| [FL"*"]M<$ZZ,ZZ9.99> 127.39 |$***127.39| The "|" character is used to denote the boundaries of the output field.
These formatting symbols can be altered by the SS modifier: Symbol Function 9 Digit selector (M format) Z Digit selector, zero suppression (M format) V Decimal alignment character (M format) .
O Overflow P Plus Z Zero Character 2 String location specifier: A Absolute F Floating P Prior n an unsigned nonzero integer constant that specifies the actual character position within the field at which the string is to begin. string any character string enclosed in quotation marks or apostrophes. NOTE: Only location type An can be used in combination with the O condition.
[MF'<',MP'>',ZPP' ']F12.2 -1000.00 | <1000.00>| MA1'CR',MPF'$']F12.2 1000.00 | $1000.00 | MA1'CR',MPF'$']F12.2 -100.00 |CR OA1'**OVERFLOW**']F12.2 1000000.00 | OA1'**OVERFLOW**']F12.2 10000000.00 |**OVERFLOW**| $100.00| 1000000.00| The "|" character is used to denote the boundaries of the output field. NOTE: These decorations are automatically applied to any numeric edit descriptor (D, E, F, G, I, or M) for which no decoration has been specified: MF'-' OA1'*** ...
List-Directed Input All input forms that are acceptable to FORMATDATA when directed by a format are acceptable for list-directed input, with these exceptions: • When the data element is a complex variable, the input form consists of a left parenthesis followed by an ordered pair of numeric input fields separated by a comma and followed by a right parenthesis.
G Superseded Guardian Procedure Calls and Their Replacements This appendix contains these tables listing superseded Guardian procedures and their replacements: • Table 48: Superseded Guardian Procedures and Their Replacements (H06.
1 This procedure can be called by TNS/R native processes. Table 51 lists the Guardian procedures that are superseded beginning in the D30 version of the operating system and indicates the new procedures that replace them. The superseded procedures continue to be supported for compatibility. Table 51 Superseded Guardian Procedures and Their Replacements (D30) Superseded Procedure Replacement Procedure DEFINEPOOL The ...POOL procedures were superseded by POOL_...
Table 52 Superseded C-Series Guardian Procedures and Their Replacements (D-Series) (continued) Superseded Procedure Replacement Procedure CONVERTPROCESSNAME FILENAME_RESOLVE_ CREATE FILE_CREATE[LIST]_ CREATEPROCESSNAME PROCESSNAME_CREATE_ CREATEREMOTENAME PROCESSNAME_CREATE_ CREATORACCESSID PROCESS_GETINFO[LIST]_ DEALLOCATESEGMENT SEGMENT_DEALLOCATE_ DEBUGPROCESS PROCESS_DEBUG_ DEVICEINFO[2] FILE_GETINFOLISTBYNAME_ FILE_GETINFOBYNAME_ DISKINFO FILE_GETINFOLISTBYNAME_ FILEINFO FILE_GETIN
Table 52 Superseded C-Series Guardian Procedures and Their Replacements (D-Series) (continued) Superseded Procedure Replacement Procedure NEWPROCESSNOWAIT PROCESS_CREATE_ and PROCESS_LAUNCH_ NEXTFILENAME FILENAME_FINDNEXT_ OPEN FILE_OPEN_ OPENEDIT OPENEDIT_ OPENINFO FILE_GETOPENINFO_ PRIORITY PROCESS_SETINFO_ or PROCESS_GETINFO[LIST]_ PROCESSACCESSID PROCESS_GETINFO[LIST]_ PROCESSFILESECURITY PROCESS_SETINFO_ or PROCESS_GETINFOLIST_ PROCESSINFO PROCESS_GETINFO[LIST]_ PROCESSTIME PROCESS
H Other Documented Guardian Procedures This list shows additional Guardian procedures that are documented in other manuals and points to the manuals in which they are described: ABORTTRANSACTION TMF Application Programmer’s Guide ACTIVATERECEIVETRANSID TMF Application Programmer’s Guide APS_... OSI/AS Programming Guide AR... TMF Application Programmer’s Guide BEGINTRANSACTION TMF Application Programmer’s Guide COMPUTETRANSID TMF Application Programmer’s Guide CPRL_...
I Using the DIVER and DELAY Programs This appendix describes the DIVER and DELAY programs which you can use to supplement the testing of an application program that runs as a process pair. DIVER causes a specified processor to fail and then prepares the processor for reload. DIVER can be used with DELAY to cause repeated failures and reloads of the processors in a system. This failure cycle allows you to test an application for fault tolerance while the processors are being halted and reloaded.
Running the DELAY Program You use the DELAY program to delay the execution of the calling process for a specified amount of time. DELAY calls the DELAY procedure for the length of time specified. After the delay finishes, the process resumes execution. The syntax to run DELAY is: DELAY / run-option [ , run-option ].../time { TIC | SEC | MIN } DELAY is an implicit RUN command that starts a DELAY process. run-option is any valid option for the TACL RUN command.
4. 5. Start your application running as a process pair in processors 0 and 1. Start the processor failure cycle by entering this command at the TACL prompt. This command starts a TACL process using DIVE0 as the IN file. > TACL /CPU 0, NAME $DIVE0, IN DIVE0, OUT $0 / 6.
J System Limits This appendix presents a series of tables that summarize the architectural and programmatic limits that apply on NonStop servers. • Table 53: System-Level Limits • Table 54: Per-Process Limits • Table 55: Per-Processor Limits • Table 56: TNS vs. Native Limits • Table 57: Enscribe File System Limits • Table 58: DP2 Limits For SQL/MP limits, see the "Limits" entry in the SQL/MP Reference Manual. For TMF limits, see the TMF Configuration and Planning Guide.
Table 53 System-Level Limits (continued) Limit Description Maximum Value Comment System-generated names (5-character form) 65,536 Names in the form $X0aaa or $X1aaa, where a is alphanumeric except e, i, o, and u. Explicitly reserved process names -- $X..., $Y..., $Z...
Table 55 Per-Processor Limits Limit Description Maximum Value Comment Processes 64K Architectural limit; current practical limit is much lower. Processes 4,000 for all G-series RVUs Time-list elements (TLEs) 3,600 for TNS/R Implementation limit. Limit is reached when 8,086 for earlier J-series and processor runs out of a resource such as CPU cycles, types of memory (operating system H-series RVUs aliased, memory, other virtual memory, or 12,100 as of H06.
Table 55 Per-Processor Limits (continued) Limit Description Maximum Value Comment use the PEEK /CPU N/ MQCINFO command Maximum MQC size 2,048 bytes6 7 8,128 bytes Higher messaging performance is achieved when a message request and/or reply is cached in an MQC. Larger MQC sizes support a wider range of message sizes that can benefit from the MQC caching optimization. 1 2 3 4 5 6 7 All G-series RVUs, H06.20 and earlier H-series RVUs, and J06.09 and earlier J-series RVUs. H06.
Table 57 Enscribe File System Limits Limit Description Maximum Value Comment File codes 64K Reserved range is limited to 0 through 999. File error numbers 64K Errors above 255 are problematic through some old interfaces. Setmodes 64K Controls 64K Setparams 64K System message numbers 32K Restricted to negative values. Concurrent opens 32,720 G-series 16,360 H-series and J-series Nowait depth Varies by device type See appropriate subsystem manual.
Table 57 Enscribe File System Limits (continued) Limit Description Maximum Value Comment Remote across Expand ~32 KB or 56 KB Depending upon Expand Local access/remote across SuperCluster 56 KB or ~2 MB ~2 MB applies to the H06.24/J06.13 and later RVUs.
Table 58 DP2 Limits (continued) Limit Description Maximum Value Disk volume size 600 GB Cache per volume 1 GB Bulk I/O transfer 56 KB bytes Number of locks 5,000 per file open and per Lock limits can be raised by using the transaction SYSGEN modifiers MAXLOCKSPEROCB and MAXLOCKSPERTCB. Maximum value for these limits is 100,000. See the System Generation Manual for Disk and Tape Devices. Configuring large values for these limits increases DP2 memory requirements and can affect DP2 response time.
K Character Set Translation Table 60 contains an ASCII-EBCDIC translation. The sum of the hexadecimal row/column headings is the EBCDIC value corresponding to the ASCII value in the body of the table. Translation is symmetric; translating the contents of any array from ASCII to EBCDIC and back, or vice versa, returns the original text. There is no recognized standard for EBCDIC, and several variations exist. The mapping of Table 60 is consistent with that in other HP products.
Index Symbols $OSP, limit on number of opens, 462, 901 $RECEIVE and CLOSE^FILE SIO procedure, 172 file obtaining the message tag, 443, 763, 1226 obtaining the process ID, 443, 763, 1226 obtaining the sync ID, 443, 1226 reading messages, 1213 replying to a message, 1242 replying to queued messages, 501, 1244 in FILE_OPEN_ procedure, 468 in OPEN procedure, 906 protocol, using INITIALIZER, 728 $X process name, 240, 242 $Y process name, 240, 242 $Z process name, 240, 242 &G'\[0] relative address, obtaining, 760
BINSEM_CREATE_, 88 BINSEM_FORCELOCK_, 91 BINSEM_ISMINE_, 97 BINSEM_LOCK_, 93, 97, 99 BINSEM_OPEN_, 101 BINSEM_UNLOCK_, 105 using, 89 Binary semaphores closing, 86, 103 creating, 88 listing processes waiting for, 1026 locking, 91, 93, 97, 99 opening, 101 unlocking, 105 BINSEM_CLOSE_ procedure, 86 BINSEM_CREATE_ procedure, 88 BINSEM_FORCELOCK_ procedure, 91 BINSEM_GETSTATS_ Procedure, 93 BINSEM_ISMINE_ procedure, 97 BINSEM_LOCK_ procedure, 99 BINSEM_OPEN_ procedure, 101 BINSEM_STAT_VERSION_ Procedure, 103 BIN
FILE_OPEN_CHKPT_, 471 GETSYNCINFO, 670 MONITORCPUS, 834, 1079 PROCESSORSTATUS, 1176 RESETSYNC, 1248 SEGMENT_ALLOCATE_CHKPT_, 1272 SEGMENT_DEALLOCATE_CHKPT_, 1279 SETSYNCINFO, 1355 CHECKPOINTMANY procedure, 145 CHECKPOINTX procedure, 149, 155 CHECKRESIZESEGMENT procedure, 161 CHECKSETMODE procedure, 162 CHECKSWITCH procedure, 164 CHILD_LOST_ procedure, 166 CLASS attribute of DEFINE, 1547 CLASS CATALOG DEFINEs, 1547 CLASS DEFAULTS DEFINEs, 1547 CLASS MAP DEFINEs, 1547 CLASS SEARCH DEFINEs, 1548 CLASS SORT DEF
in GETREMOTECRTPID procedure, 668 in MYPID procedure, 842 in PROCESSINFO procedure, 1147 CPU interval clock, obtaining internal, form, 1424 CPU time spent since system load, 1162 CREATE procedure description of, 228 failures, 235 CREATEPROCESSNAME procedure, 239 CREATEREMOTENAME procedure, 241 Creating files structured, 228, 385, 392 unstructured, 228, 385, 392 process names, 1153 Creation timestamp, 655 Creator access ID (CAID) description of, 1009 of a new process, 860, 994, 1117 returned value, 243 Creat
DEFINENEXTNAME, 272 DEFINEREADATTR, 277 DEFINERESTORE, 281 DEFINERESTOREWORK\[2], 284 DEFINESAVE, 285 DEFINESAVEWORK\[2], 288 DEFINESETATTR, 289 DEFINESETLIKE, 292 DEFINEVALIDATEWORK, 294 DEFINEADD procedure, 259 DEFINEDELETE procedure, 261 DEFINEDELETEALL procedure, 263 DEFINEINFO procedure, 264 DEFINELIST procedure, 267 DEFINEMODE procedure, 270 DEFINENEXTNAME procedure, 272 DEFINEPOOL procedure, 274 DEFINEREADATTR procedure, 277 DEFINERESTORE procedure, 281 DEFINERESTOREWORK\[2] procedures, 284 DEFINEs a
permanent, 228, 385, 392 physical record length, 314, 316, 408 positioning a disk file to a saved position, 1246 random processing and WRITEUPDATE, 540, 1513 random read processing, 1213 reading a record after calling:KEYPOSITION, 1221 reading a record after calling:POSITION, 1221 record length, 230, 387–388 refreshing, 390 repositioning disk heads, 753 returning the primary extent size, 416, 552 returning the RBA location, 552 saving a disk file's current file position, 1257 security check, 464, 903 select
Example of a Guardian procedure call, 34 Exclusion mode checking, on open, 465, 904 Exclusive file opens, using pseudo-temporary names, 240 Execution priority changing, 67, 980, 985, 1083–1084 of a new process, 847, 985, 1050, 1095 Execution time of a calling process returned, 843 of a process measured, 1378 of any process in the network, 1183 setting a timer based on execution, 1377 Expanding file names external to internal form, 618 network names, 618 Exponential edit descriptor, 1557 EXTDECS, 32 Extended
to process handles, 600 converting:external to internal form, 618 converting:to Guardian file names, 934 decomposing, 566 editing, 569 expanding, 618 for nondisk devices, 1537 fully and partially qualified, 1536, 1540 obtaining, in alphabetic order, 863 reserved, 1536 unresolving, 602 File opening, 457, 897 File position by primary key, 975 saving, 504, 1257 File purging, 473, 1186 File reading, 1192, 1213 File security checking, 464, 903 examining, 1132 level, 464, 903 setting for the current process, 1132
WRITEUPDATEUNLOCK\[X\], 1516 FILE_ALTERLIST_ procedure, 346 FILE_AWAITIO64_ procedure, 353 summary of actions, 356 summary of operations, 356 FILE_CLOSE_ procedure, 362 FILE_CLOSE_CHKPT_ procedure, 364 FILE_COMPLETE\[L\]_ procedure, 366 FILE_COMPLETE_GETINFO_ procedure, 373 FILE_COMPLETE_SET_ procedure, 375 FILE_CONTROL64_ procedure, 379 FILE_CONTROLBUF64_ procedure, 382 FILE_CREATE_ procedure, 385 FILE_CREATELIST_ procedure, 392 FILE_GETINFO_ procedure description of, 404 OSS file, identifying, 405 FILE_GE
REPOSITION procedure, 1246 RESETSYNC procedure, 1248 SAVEPOSITION procedure, 1257 SETMODE procedure, 1318 SETMODENOWAIT procedure, 1346 SETPARAM procedure, 1349 SETSYNCINFO procedure, 1355 UNLOCKFILE procedure, 1434 UNLOCKREC procedure, 1437 WRITE\[X\] procedure, 1491 WRITEEDIT procedure, 1499 WRITEEDITP procedure, 1502 WRITEREAD\[X\] procedure, 1505 WRITEUPDATE\[X\]procedure, 1510 WRITEUPDATEUNLOCK\[X\] procedure, 1517 FILERECINFO procedure, 605 Fill-character modifier, 1565 Fixed-format edit descriptor, 1
HEADROOM_ENSURE_ procedure, 691 HEAPSORT procedure, 693 HEAPSORTX_ procedure, 695 Hexadecimal edit descriptor, 1565 HIST_FORMAT_ procedure, 698 HIST_GETPRIOR_ procedure, 714 HIST_INIT_ procedure, 716 Hollerith constant, 1553 Home terminal changing default home terminal, 1348 obtaining file name, 845 I I edit descriptor, 1560 I/O completion, on IOEdit files, 177 I/O completion, with and without SETMODE 30, 82, 359 I/O data buffer, for device-dependent operations, 212 I/O file operations completing waiting,
KEYPOSITION\[X\] procedures and file-system error 21, 756 description of, 750 Logical record length, 415, 607 LOOKUPPROCESSNAME procedure, 781 LST see Local standard time L M L edit descriptor, 1562 LABELEDTAPESUPPORT procedure, 759 Labels, for corresponding named entry points, 1413–1414 Last record in a file, positioning, 755 LASTADDR procedure, 760 LASTADDRX procedure, 761 LASTRECEIVE procedure, 763 LCT see Local civil time Left-justify modifier, 1566 Library conflict, 859 Library file user and progra
Memory usage information, obtaining, 1161 Memory, block of obtaining from a buffer pool, 661, 945 returning to a buffer pool, 949, 1188 Memory-management procedures ALLOCATESEGMENT, 58 CURRENTSPACE, 247 DEALLOCATESEGMENT, 252 DEFINEPOOL, 274 GETPOOL, 661 POOL_CHECK_, 937 POOL_DEFINE_, 939 POOL_GETINFO_, 942 POOL_GETSPACE_, 945 POOL_PUTSPACE_, 949 POOL_RESIZE_, 951 PUTPOOL, 1188 RESIZEPOOL, 1250 USESEGMENT, 1480 Merge functions see Sort functions Message-system procedures, CONTROLMESSAGESYSTEM, 215 MESSAGEST
NSK_FLOAT_TNS32_TO_IEEE64_ Procedure;IEEE floating point conversion procedures NSK_FLOAT_TNS32_TO_IEEE64_, 878 NSK_FLOAT_TNS64_TO_IEEE64_ Procedure;IEEE floating point conversion procedures NSK_FLOAT_TNS64_TO_IEEE64_, 878 Null process handle, creating, 1140 Null value for an alternate-key field, 232 NUMBEREDIT procedure, 881 NUMIN procedure, 883 NUMOUT procedure, 885 O O edit descriptor, 1564 Object file, obtaining information about, 888 OBJFILE_GETINFOLIST_ procedure, 888 OC modifier, 1566 Octal edit desc
in structured files, 506, 750 saving, 753 POSITIONEDIT procedure, 978 Positioning by primary key, in key-sequenced files, 506, 750 by primary key, in relative and entry, by sequenced files, 514, 975 in an EDIT file, 978 in unstructured files, 514, 975 saving a current position, 504, 1257 to a saved position, 502, 1246 to the last record in a file, 755 to the start of a file, 754 Positioning block, 502, 1246, 1257 Power On messages, enabling or disabling receipt of, 837, 1082 PPD see Process pair directory P
SETSTOP, 1353 SIGNALPROCESSTIMEOUT, 1377 SIGNALTIMEOUT, 1380, 1390, 1393 STEPMOM, 1395 STOP, 1398 SUSPENDPROCESS, 1406 Process creation errors indicating outcome, 850, 992, 1052 Process data stack checkpointing, 143, 147 Process descriptors, 1539 Process file name C-series syntax, 1543 D-series syntax for unnamed processes, 1537 or named processes, 1538 Process handle comparing, 1134 converting to process file name, 1143 to process ID, 1141 to process string, 1145 converting:to file name, 1143 decomposing,
PROCESSHANDLE_GETMINE_ procedure, 1139 PROCESSHANDLE_NULLIT_ procedure, 1140 PROCESSHANDLE_TO_CRTPID_ procedure, 1141 PROCESSHANDLE_TO_FILENAME_ procedure, 1143 PROCESSHANDLE_TO_STRING_ procedure, 1145 PROCESSINFO procedure, 1147 Processing decorations, 1568 PROCESSNAME_CREATE_ procedure, 1153 Processor configuration information, obtaining, 1156 failures, 834, 1079 name, obtaining, 1172 statistics, obtaining, 1156 status, count and operational state, 1176 enabling or disabling receipt of, 1081 obtaining in
S S edit descriptor, 1554 Sample of a Guardian procedure call, 34 SAVEPOSITION procedure, 1257 Scale factor, 630, 635 Scale factor edit descriptor, 1550, 1553 Scanning file names, 591 for a process string, 1180 Secondary extent size returning, 416, 553 specifying, 229, 386, 395 Security check on disk file opens, 464, 903 Security procedures, CREATORACCESSID, 243 Security system procedures PROCESSACCESSID, 1131 PROCESSFILESECURITY, 1132 USER_AUTHENTICATE_, 1441 USER_GETINFO_, 1452 USER_GETNEXT_, 1458 USERDEF
SS edit descriptor, 1554 SS modifier, 1566 SSIDTOTEXT Procedure, 1388 Stack addresses to extended addresses, 275, 940 Stack base for checkpointing, 142 Stack marker ENV register and the space ID, 72 Stack marker ENV register, and the space ID, a procedure that returns, 248 Stack registers R0-R7 concerning trap handlers, 71 Stack, user's designate use as a pool, 274, 937, 939, 942 STACK_ALLOCATE_ procedure, 1390 STACK_DEALLOCATE_ procedure, 1393 Start of a file, positioning, 754 Startup message, reading, 726
Time and day array form, 734 Time limit in AWAITIO\[X|\XL\] procedure, 79 in FILE_COMPLETE\[L\]_ procedure, 367 Time measured elapsed time that process executes, 1381 while the process is executing, 1378 TIME procedure, 1420 Timeout during AWAITIO\[X] before completion, 76, 353 summary of actions, 80 Timeout during AWAITIO\[X|\XL\] error indication, 83 Timeout during FILE_AWAITIO64_ error indication, 359 summary of actions, 356 Timeout during FILE_COMPLETE_, before completion, 366 Timer based on process exe
USER_GETINFO_ procedure, 1452 USER_GETNEXT_ procedure, 1458 USERDEFAULTS procedure, 1461 USEREVENT_AWAKE_ procedure, 1466 USEREVENT_GET_ procedure, 1468 USEREVENT_SET_ procedure, 1469 USEREVENT_WAIT_ procedure, 1471 USEREVENTFILE_REGISTER_ procedure, 1473 USERIDTOUSERNAME procedure, 1475 USERNAMETOUSERID procedure, 1478 USESEGMENT procedure, 1480 Utility procedures ADDDSTTRANSITION, 47 ADDRESS_DELIMIT_, 49 CHECKRESIZESEGMENT, 161 CONTIME, 204 CONVERTPROCESSNAME, 218 CONVERTPROCESSTIME, 219 CONVERTTIMESTAMP,
