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. Product Version N/A Supported Release Version Updates (RVUs) This manual supports the G06.25 RVU and all subsequent G-series RVUs, and H06.03 and all subsequent H-series RVUs until otherwise indicated by its replacement publication.
Document History Part Number Product Version Published 522629-008 Guardian G09 September 2004 522629-010 N/A November 2004 522629-011 N/A February 2005 522629-012 N/A May 2005 522629-013 N/A July 2005
Guardian Procedure Calls Reference Manual Index Figures Tables What’s New in This Manual i Manual Information i New and Changed Information About This Manual i Notation Conventions i vi 1.
3. Guardian Procedure Calls (C) Contents ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) AWAITIO[X] Procedures 2-44 BACKSPACEEDIT Procedure 2-55 BINSEM_CLOSE_ Procedure 2-57 BINSEM_CREATE_ Procedure 2-59 BINSEM_FORCELOCK_ Procedure 2-63 BINSEM_LOCK_ Procedure 2-66 BINSEM_OPEN_ Procedure 2-69 BINSEM_UNLOCK_ Procedure 2-72 BREAKMESSAGE_SEND_ Procedure 2-74 2-35 3.
4.
Contents 4.
5. Guardian Procedure Calls (F) Contents 5.
6.
7.
9. Guardian Procedure Calls (M) Contents LOCATESYSTEM Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure ) 8-9 LOCKFILE Procedure 8-11 LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) 8-15 LOCKREC Procedure 8-20 LONGJMP_ Procedure 8-24 LOOKUPPROCESSNAME Procedure (Superseded by PROCESS_GETPAIRINFO_ Procedure ) 8-27 9.
10. Guardian Procedure Calls (N) Contents MYSYSTEMNUMBER Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure or PROCESSHANDLE_GETMINE_ Procedure and PROCESSHANDLE_DECOMPOSE_ Procedure ) 9-75 MYTERM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) 9-77 10.
. Guardian Procedure Calls (P) Contents 12.
. Guardian Procedure Calls (R) Contents PROCESSHANDLE_TO_STRING_ Procedure 12-220 PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) 12-223 PROCESSNAME_CREATE_ Procedure 12-231 PROCESSOR_GETINFOLIST_ Procedure 12-234 PROCESSOR_GETNAME_ Procedure 12-250 PROCESSORSTATUS Procedure 12-255 PROCESSORTYPE Procedure 12-257 PROCESSSTRING_SCAN_ Procedure 12-259 PROCESSTIME Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) 12-263 PROGRAMFILENAME Procedure (Superseded by PROCESS_GETINFOLI
. Guardian Procedure Calls (S) Contents 14.
. Guardian Procedure Calls (T-V) Contents SIGNALTIMEOUT Procedure 14-149 SIGPENDING_ Procedure 14-153 SIGPROCMASK_ Procedure 14-154 SIGSETJMP_ Procedure 14-155 SIGSUSPEND_ Procedure 14-158 SSIDTOTEXT Procedure 14-159 STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) 14-167 STRING_UPSHIFT_ Procedure 14-174 SUSPENDPROCESS Procedure (Superseded by PROCESS_SUSPEND_ Procedure ) 14-176 SYSTEMENTRYPOINT_RISC_ Procedure 14-178 SYSTEMENTRYPOINTL
. Guardian Procedure Calls (W-Z) Contents 16. Guardian Procedure Calls (W-Z) WAIT^FILE Procedure 16-2 WRITE[X] Procedures 16-4 WRITE^FILE Procedure 16-12 WRITEEDIT Procedure 16-15 WRITEEDITP Procedure 16-18 WRITEREAD[X] Procedures 16-20 WRITEUPDATE[X] Procedures 16-25 WRITEUPDATEUNLOCK[X] Procedures 16-33 XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK_ Procedure ) 16-39 XSTACKTEST Procedure (Superseded by HEADROOM_ENSURE_ Procedure ) 16-42 A. Device Types and Subtypes B.
F. Formatter Edit Descriptors Contents DEFINE Attributes E-2 Available DEFINE Classes E-3 CLASS CATALOG DEFINEs E-3 CLASS DEFAULTS DEFINEs E-3 CLASS MAP DEFINEs E-3 CLASS SEARCH DEFINEs E-4 CLASS SORT DEFINEs E-4 CLASS SUBSORT DEFINEs E-4 CLASS SPOOL DEFINEs E-5 CLASS TAPE DEFINEs E-5 CLASS TAPECATALOG DEFINEs E-5 F.
G. Superseded Guardian Procedure Calls and Their Replacements Contents Fill-Character Modifier (FL) F-23 Overflow-Character Modifier (OC) F-24 Justification Modifiers (LJ, RJ) F-24 Symbol-Substitution Modifier (SS) F-24 Decorations F-26 Conditions F-26 Locations F-27 Processing F-27 List-Directed Formatting F-29 List-Directed Input F-29 List-Directed Output F-30 G. Superseded Guardian Procedure Calls and Their Replacements H. Documented Guardian Procedures I.
Tables (continued) Contents Tables (continued) Table 2-3. Table 3-1. Table 3-2. Table 3-3. Table 3-4. Table 3-5. Table 4-1. Table 4-2. Table 5-1. Table 5-2. Table 5-3. Table 5-4. Table 5-5. Table 5-6. Table 5-7. Table 5-8. Table 5-9. Table 6-1. Table 7-1. Table 8-1. Table 9-1. Table 10-1. Table 10-2. Table 11-1. Table 11-2. Table 11-3. Table 11-4. Table 11-5. Table 12-1. Table 12-2. Table 12-3. Table 12-4. Table 12-5. Table 12-6. Table 13-1.
Tables (continued) Contents Tables (continued) Table 14-1. Table 14-2. Table 14-3. Table 14-4. Table 15-1. Table 16-1. Table A-1. Table G-1. Table G-2. Table G-3. Table G-4. Table G-5. Table J-1. Table J-2. Table J-3. Table J-4. Table J-5. Table J-6. Table J-7. Table K-1.
What’s New in This Manual Manual Information 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. Product Version N/A Supported Release Version Updates (RVUs) This manual supports the G06.25 RVU and all subsequent G-series RVUs, and H06.03 and all subsequent H-series RVUs until otherwise indicated by its replacement publication.
What’s New in This Manual • • • • • • • New and Changed Information TIMER_START_ Procedure (H-Series RVUs Only) TIMER_STOP_ Procedure (H-Series RVUs Only) TS_NANOSECS_ Procedure (H-Series RVUs Only) TS_UNIQUE_COMPARE_ Procedure (H-Series RVUs Only) TS_UNIQUE_CONVERT_TO_JULIAN_ Procedure (H-Series RVUs Only)_ TS_UNIQUE_CREATE_ Procedure (H-Series RVUs Only) Added a note to these commands about H-series changes to the CEXTDECS file: • • • • • • • • • • • • • • • • • • • • • ADDRESS_DELIMIT_ Procedure A
What’s New in This Manual • • • • • • • • • • • • • • • • • • • New and Changed Information READEDIT Procedure READEDITP Procedure SEGMENT_ALLOCATE_ Procedure SEGMENT_GETINFO_ Procedure SEGMENT_USE_ Procedure SSIDTOTEXT Procedure TEXTTOSSID Procedure USER_GETINFO_ Procedure WRITEEDIT Procedure Section 1, Introduction to Guardian Procedure Calls contains new information about H-series procedure calls and changes to the CEXTDECS file.
What’s New in This Manual • • • • • • • • • • • • • • • • • • New and Changed Information Changed the value of the timeout parameter in the C Syntax for C Programmers example to be int64 instead of uint64. Added the new procedure VRO_SET_ Procedure (H-Series RVUs Only). Added disk subtypes 52 and 53 to Appendix A, Device Types and Subtypes. Added new error messages 80, 81, 82,83, 84, and 99 to Table 12-3, Summary of Process Creation Errors.
What’s New in This Manual • • • • • New and Changed Information Solution 10-050330-6129 Solution 10-050329-6085 Solution 10-050328-6056 Solution 10-050311-5548 Solution 10-050318-5755 Guardian Procedure Calls Reference Manual—522629-013 xxiii
About This Manual This reference manual describes the syntax of most of the Guardian procedure calls. This manual is for programmers who need to call Guardian procedures from their programs. Familiarity with TAL or some other programming language is recommended.
Notation Conventions About This Manual Appendix C, Completion Codes lists the completion codes returned after execution of a process that indicate, in a standard manner, its degree of success. Appendix D, File Names and Process Identifiersdescribes reserved file names, Cseries and D-series syntax for file names and process identifiers, and the syntax for OSS pathnames. Appendix E, DEFINEsdescribes DEFINEs and lists the attributes of all classes of DEFINEs.
General Syntax Notation About This Manual computer type. Computer type letters within text indicate C and Open System Services (OSS) keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: myfile.c italic computer type. Italic computer type letters within text indicate C and Open System Services (OSS) variable items that you supply. Items not enclosed in brackets are required. For example: pathname [ ] Brackets.
General Syntax Notation About This Manual Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be typed as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must type as shown. For example: "[" repetition-constant-list "]" Item Spacing.
Notation for Messages About This Manual !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum , [ filename:maxlen ] ) ; !i !o:i Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. Bold Text. Bold text in an example indicates user input typed at the terminal.
Notation for Management Programming Interfaces About This Manual either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: obj-type obj-name state changed to state, caused by { Object | Operator | Service } process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } | Vertical Line.
Change Bar Notation About This Manual Change Bar Notation Change bars are used to indicate substantive differences between this manual and its preceding version. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL85 environment and the Common Run-Time Environment (CRE).
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.
Introduction to Guardian Procedure Calls You can also call Guardian procedures from programs written in FORTRAN, BASIC, COBOL, or C++. How a Guardian procedure is called depends on the programming language. Some languages provide extensions for calling Guardian procedures. Some languages (other than TAL) allow your code to contain TAL code that calls Guardian procedures using TAL syntax.
Introduction to Guardian Procedure Calls Types of Guardian Procedure Calls Types of Guardian Procedure Calls Table 1-1 shows the types of Guardian procedures that are described in this manual. It also shows the manuals where you can find programming information about these procedures. Refer to Appendix H, Documented Guardian Procedures for a complete list of all documented Guardian procedures and the manuals in which they are described. Table 1-1.
Introduction to Guardian Procedure Calls H-Series Guardian Procedures handling, and utility procedures). However, the Guardian Procedure Calls Reference Manual presents Guardian procedure descriptions in alphabetical order.
Introduction to Guardian Procedure Calls External Declarations Files for Guardian Procedures External Declarations Files for Guardian Procedures Like all procedures in an application program, Guardian procedures must be declared before they can be called. Guardian procedures are declared as external procedures. A $SYSTEM.SYSTEM file contains many of the Guardian procedure declarations for each programming language. For example: • • pTAL declarations are in $SYSTEM.SYSTEM.EXTDECS0.
Introduction to Guardian Procedure Calls Parameter Declarations Files for Guardian Procedures Parameter Declarations Files for Guardian Procedures HP provides a set of declarations, consisting mainly of named constants (literals) and structure definitions, that can be used for parameters to Guardian procedures. Data Definition Language (DDL) is used to generate files containing the parameter declarations for TAL, COBOL, Pascal, and C. These files are located on the subvolume $SYSTEM.ZSYSDEFS.
TAL Syntax for a Guardian Procedure Call Introduction to Guardian Procedure Calls 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-1. Sample TAL Syntax for a Procedure Call 1 2 4 3 { error := } NODENAME_TO_NODENUMBER_ ( nodenam e:length ! i:i { CALL } ,no denumber ); ! o error returned value INT is a file-system error number indicating the outcome of the operation. 5 nodename:length input:inpu t 6 STRING .
Introduction to Guardian Procedure Calls 1 TAL Syntax for a Guardian Procedure Call 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. For function procedures that set the condition code, you must declare the return variable as a simple variable.
TAL Syntax for a Guardian Procedure Call Introduction to Guardian Procedure Calls INT 16-bit integer INT(32) 32-bit integer STRING character string (8-bit character) FIXED 64-bit fixed-point number REAL 32-bit floating-point number EXTADDR 32-bit address Refer to the pTAL Reference Manual for a complete discussion of formal parameter specifications. The parameter type is followed by a colon.
Introduction to Guardian Procedure Calls String Output Variables String Output Variables The syntax for some Guardian procedures contains one or more sets of three parameters that are grouped together, where each set describes a string output variable. Figure 1-2 shows an example of this use. Note that the first two parameters are separated by a colon. (See Figure 1-1 for a general description of the use of two parameters separated by a colon.
Introduction to Guardian Procedure Calls Bounds Checking of Reference Parameters for Guardian Procedures Those Guardian procedures that use a different local data stack copy the caller’s parameters to that stack before proceeding. Because the reference parameter does not then intrude into the Guardian procedure’s local data stack, it does not cause a bounds violation error.
Introduction to Guardian Procedure Calls C Syntax for a Guardian Procedure Call 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. For further information on calling Guardian procedures from a C program, refer to the C/C++ Programmer’s Guide. Figure 1-3 shows an example of C syntax. As in TAL syntax, square brackets ([ ]) indicate optional parameters.
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 2-1 lists all the procedures in this section. Table 2-1.
Guardian Procedure Calls (A-B) ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations NetBatch Considerations Messages OSS Considerations Examples Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) Guardian Procedure Calls (A-B) previous software. 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 input process-id INT:ref:4 indicates the process that is to be stopped. At this point, you have two options.
Guardian Procedure Calls (A-B) ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) designated process. If it makes the request successfully (error is 0), the designated process might or might not be stopped depending on the stopmode of the process and the authority of the caller. (The stop mode of the process can be changed; hence, a stop request that has inadequate authority to stop the process is saved by the system and might succeed at a later time.) See “Considerations.
Guardian Procedure Calls (A-B) ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) Condition Code Settings A condition code value is returned only when a process is calling ABEND on another process and that other process could not be terminated. < (CCL) indicates that either the process-id parameter is invalid or an error occurred during termination of the process. = (CCE) indicates that ABEND was successful. > (CCG) is not returned from ABEND.
Guardian Procedure Calls (A-B) • • • • • ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) A network super ID The process’s network process access ID The process’s network process access ID group manager The process’s network creator access ID The process’s network creator access ID group manager where network ID implies that the user IDs or associated process creators have matching remote passwords.
Guardian Procedure Calls (A-B) • • ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) If a process calls ABEND on another process, the system supplies a completion code value of 6. If a process calls ABEND on itself but does not supply a completion code, the system supplies a completion code value of 5. Refer to Appendix C, Completion Codes for a list of the completion codes.
ABEND Procedure (Superseded by PROCESS_STOP_ Procedure ) Guardian Procedure Calls (A-B) • • The pid parameter set to the OSS process ID of the process identified by processhandle in the PROCESS_STOP_ call The security rules that apply to terminating an OSS process using ABEND are the same as those that apply to the OSS kill() function. See the kill(2) function reference pages either online or in the Open System Services System Calls Reference Manual for details.
Guardian Procedure Calls (A-B) ACTIVATEPROCESS Procedure (Superseded by PROCESS_ACTIVATE_ ACTIVATEPROCESS Procedure (Superseded by PROCESS_ACTIVATE_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (A-B) ACTIVATEPROCESS Procedure (Superseded by PROCESS_ACTIVATE_ .<8:15> PIN assigned by the operating system to identify the process in the processor If process-id [0:2] references a process pair and process-id [3] is specified as -1, then both members of the process pair are activated. Condition Code Settings < (CCL) indicates that either ACTIVATEPROCESS failed or no process designated as process-id exists. = (CCE) indicates that the process is activated.
Guardian Procedure Calls (A-B) ADDDSTTRANSITION Procedure (Superseded by DST_GETINFO_ Procedure) 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.
Guardian Procedure Calls (A-B) ADDDSTTRANSITION Procedure (Superseded by DST_GETINFO_ Procedure) parameter of the previous call. This implies that many calls have an offset parameter of 0. input high-gmt FIXED:value is the GMT when offset is no longer applicable.
Guardian Procedure Calls (A-B) ADDRESS_DELIMIT_ Procedure ADDRESS_DELIMIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Address-Descriptor Bit Fields Reserved Segment ID Values Example Related Programming Manual Summary The ADDRESS_DELIMIT_ procedure obtains the addresses of the first and last bytes of a particular area of the caller’s logical address space.
Guardian Procedure Calls (A-B) ADDRESS_DELIMIT_ Procedure 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. This error is returned only to nonprivileged callers. 4 The address parameter is not mapped. 5 The address parameter is one of the following: • • • An invalid address (address.
Guardian Procedure Calls (A-B) ADDRESS_DELIMIT_ Procedure returns the logical segment ID of the address area that contains address. Either this is the segment ID assigned by the caller when the segment was allocated, or it is a reserved segment ID. See “Reserved Segment ID Values,” later in this section, for details. If error is 4 (address is not mapped), segment-id returns -1. error-detail output INT .EXT:ref:1 returns additional error information when an error value of 3 (bounds error) is returned.
Guardian Procedure Calls (A-B) ADDRESS_DELIMIT_ Procedure 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. For some kinds of segments (such as SRL or DLL code or instance data), multiple segments in the process can have the same ID. Segment ID assignments are subject to change from RVU to RVU; the individual values are not meaningful to typical callers of ADDRESS_DELIMIT_.
Guardian Procedure Calls (A-B) ADDRTOPROCNAME Procedure ADDRTOPROCNAME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (A-B) ADDRTOPROCNAME Procedure Parameters returned value error INT returns a file-system error code indicating the outcome of the call, as follows: 0 Successful call; the procedure name is deposited into proc-name for proc-name-length bytes. 11 A procedure name was not found.
Guardian Procedure Calls (A-B) ADDRTOPROCNAME Procedure input proc-name-size INT:value is the size, in bytes, of the caller’s proc-name buffer. proc-name-length output INT .EXT:ref:1 is the length, in bytes, of the procedure name string returned into proc-name. output base INT .EXT:ref:1 is the base word address (first word) of the procedure indicated by proc-name. output size INT .EXT:ref:1 is the size, in words, of the procedure indicated by proc-name. output entry INT .
ADDRTOPROCNAME Procedure Guardian Procedure Calls (A-B) Considerations • • The maximum value of proc-name-length, and hence the address space that must be available at the location given by proc-name, depends on the language that was used to create the code to which p-reg, stack-env, and the optional pin refer. Read access to the associated object file is not required in order to obtain the requested output parameters associated with the given p-reg, stack-env, and optional pin.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ Syntax for TAL Programmers status := ALLOCATESEGMENT ( segment-id ,[ segment-size ] ,[ file-name ] ,[ pin-and-flags ] ); ! ! ! ! i i i,o i Parameters returned value status INT indicates the outcome of the call: 0 No error 1-999 File-system error related to the creation or open of the swap file (see file-name parameter). -1 Illegal segment-id . -2 Illegal segment-size. -3 Bounds violation on file-name.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ segment-size input INT(32):value specifies the size in bytes of the segment to be allocated. Flat segment size: • • For G04.00 and earlier G-series RVUs the value must be in the range 1 byte through 128 megabytes (134,217,728 bytes). A flat segment is allocated beginning on a 32-megabyte region boundary and is allocated from a total virtual space of 480 megabytes (15 regions * 32 megabytes/region). For G05.
Guardian Procedure Calls (A-B) • • ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ 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). If the segment is a read-write segment, the default segment size is the allocated size of the file. For a read-only segment, segment-size must not be greater than the end-offile value of the file; otherwise, an error occurs.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ bit 1 is set to 1 (see bit <1> later). A shared segment is an extended data segment that can be shared with other processes in the same processor. <5:7> Not used; must be zero (0). <4> If 1, requests allocation of an “extensible segment.” An extensible segment is an extended data segment for which the underlying swap file disk space is not allocated until needed.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ Examples of valid pin-and-flags word values are: %000nnn Allocate a shared segment, to be shared using the PIN method with the process identified by the PIN specified in nnn. %040000 Standard call to allocate a segment (default values). %044000 Allocate an extensible segment. %050000 Allocate a segment to be shared by the file-name method.
Guardian Procedure Calls (A-B) ALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_ Callers of ALLOCATESEGMENT can share segments with callers of SEGMENT_ALLOCATE_. 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. (Similarly, a process cannot share a selectable segment with a process that allocated a flat segment.
Guardian Procedure Calls (A-B) ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure ) ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (A-B) ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure ) input newvalue INT:ref:* is an integer array supplying the new value for the characteristic specified by function. Its size is dependent on the operation. See Table 2-2. input partonly INT:value if present, specifies for partitioned files whether the function is to be performed for all partitions of the file (if the value given is zero), or just for the named partition (if the value is one).
Guardian Procedure Calls (A-B) ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure ) Table 2-2. ALTER Function Codes (page 1 of 2) Code Description 1 File-code: Change the application defined file code associated with the file. File codes 100-999 are reserved for use by HP. The newvalue parameter should be a one-word binary number. Audited: Change the TMF audited characteristic of the file (file-type.<2> from FILEINFO or item 66 from FILE_GETINFOLIST[BYNAME] _ ) .
Guardian Procedure Calls (A-B) ALTER Procedure (Superseded by FILE_ALTERLIST_ Procedure ) Table 2-2. ALTER Function Codes (page 2 of 2) Code Description 6 Partitions: Change the partitioning description of the file. The newvalue parameter should be an array in the same format as the partition-params array of the CREATE procedure. The partition description can be changed only in the following ways: a) The volume name of an existing partition may change.
Guardian Procedure Calls (A-B) ALTERPRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure ) 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.
ALTERPRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure ) Guardian Procedure Calls (A-B) .<8:15> PIN assigned by the operating system to identify the process in the processor If process-id [0:2] references a process pair and process-id [3] is specified as -1, then the call applies to both members of the process pair. input priority INT:value is a new execution priority value in the range of {1:199} for process-id.
Guardian Procedure Calls (A-B) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters ARMTRAP 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.
Guardian Procedure Calls (A-B) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Parameters traphandlr-addr input INT:value is a label (nonzero P register value) that identifies a statement in the program where control is to transfer if a trap occurs. You can specify 0 for traphandlr-addr only in a call from within a trap handler. Such a call causes the process to resume. See “Considerations” for details.
Guardian Procedure Calls (A-B) • ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Resume the process and disarm all trap handling. This must be done by a call to ARMTRAP from within a trap handler with traphandlr-addr set to 0 and trapstack-addr set to a negative value. See “Considerations” for details.
Guardian Procedure Calls (A-B) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) 'L'[-2] New value for P register 'L'[-1] New value for hardware ENV register 'L'[0] New value for L register 'L'[1] New value for R0 'L'[2] New value for R1 'L'[3] New value for R2 'L'[4] New value for R3 'L'[5] New value for R4 'L'[6] New value for R5 'L'[7] New value for R6 'L'[8] New value for R7 Note that parts of ‘L’[-5] and ‘L’[-1] are combined into the new space ID.
Guardian Procedure Calls (A-B) • ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) 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 .EXT X(X_TEMPLATE) = 'L' + 12; Assuming that the trap handler begins with the statement CODE ( PUSH %777 ), the first local variable should be placed at ‘L’+9.
Guardian Procedure Calls (A-B) • ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Terminating a trap handler A trap handler can terminate in the following ways on either a TNS or native system: • • • • Clear the overflow (or trap) bit in the trap ENV variable and resume from a trap 2 (arithmetic overflow). See “Resuming at the point of the trap” later in “Considerations.
Guardian Procedure Calls (A-B) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) or trap bit of the trap ENV variable at ‘L’[-1]. Such resumption is valid only for trap 2 (arithmetic overflow) or trap 4 (loop timeout). An attempt to resume at the point of any other trap typically causes the same trap to occur again on a TNS system; on a native system, such an attempt causes the process to abend.
Guardian Procedure Calls (A-B) • ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Invalid trap ENV fields For a process running in accelerated mode, the ENV field RP is not valid and the fields N, Z, and K are not reliable. • Register stack R[0:7] The contents of the TNS register stack are not valid in accelerated mode and are not dependable in TNS mode. You should never change the register stack when attempting to resume at the point of the trap.
Guardian Procedure Calls (A-B) ARMTRAP Procedure (Superseded by SIGACTION_INIT_ Procedure ) Related Programming Manual For programming information about the ARMTRAP trap-handling procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (A-B) AWAITIO[X] Procedures AWAITIO[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Related Programming Manual Summary The AWAITIO and AWAITIOX procedures are used to complete a previously initiated I/O operation. Use AWAITIOX with the extended 32-bit (or ‘X’) versions of the I/O procedures such as READX, WRITEREADX, and so forth.
AWAITIO[X] Procedures Guardian Procedure Calls (A-B) Syntax for C Programmers #include _cc_status AWAITIO ( short _near *filenum ,[ short _near *buffer-addr ] ,[ short _near *count-transferred ] ,[ __int32_t _near *tag ] ,[ __int32_t timelimit ] ); #include _cc_status AWAITIOX ( short *filenum ,[ __int32_t *buffer-addr ] ,[ short *count-transferred ] ,[ __int32_t *tag ] ,[ __int32_t timelimit ] ,[ short *segment-id ] ); • The function value returned by AWAITIO[X]
AWAITIO[X] Procedures Guardian Procedure Calls (A-B) output buffer-addr WADDR:ref:1 (Use with AWAITIO) returns the address of the buffer specified when the operation was initiated. EXTADDR .EXT:ref:1 (Use with AWAITIOX) returns the relative extended address of the buffer specified when the operation was initiated. If the actual parameter is used as an address pointer to the returned data and is declared in the form INT .EXT buffer-addr, then it should be passed to AWAITIO[X] in the form @buffer-addr.
Guardian Procedure Calls (A-B) AWAITIO[X] Procedures output segment-id INT .EXT:ref:1 (Use with AWAITIOX only) returns the segment ID of the extended data segment containing the buffer when the operation was initiated. If the buffer is not in a selectable segment, segment-id is -1. Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that an I/O operation completed.
AWAITIO[X] Procedures Guardian Procedure Calls (A-B) dequeued record is reinserted into the file. For nonaudited queue files, there is no means of assuring recovery of a lost record. Thus, your application should never call AWAITIO[X] with a time limit greater than 0D if READUPDATELOCK[X] is pending. The ABORTTRANSACTION recovery procedure does not work on nonaudited queue files.
Guardian Procedure Calls (A-B) • AWAITIO[X] Procedures Reference parameters for AWAITIOX The reference parameters for AWAITIOX can be in the user’s stack or in an extended data segment. The reference parameters cannot be in the user’s code space. The reference parameters for AWAITIOX must be relative extended addresses; they cannot be absolute extended addresses.
Guardian Procedure Calls (A-B) AWAITIO[X] Procedures operation should not be used for any other purpose (including another read) until the read operation has been completed with a call to AWAITIO[X]. • No nowaited operations You should not call AWAITIO[X] unless you initiate a nowait operation prior to the call; otherwise, an error indication returns (CCL). A subsequent call to FILE_GETINFO_ or FILEINFO shows that an error 26 occurred.
AWAITIO[X] Procedures Guardian Procedure Calls (A-B) Table 2-3. AWAITIO[X] Action Particular File filenum = a file number Any File filenum = –1 timelimit = 0 timelimit <> 0 CHECK for any I/O completion on filenum. COMPLETION File number is returned in filenum. Tag of completed call is returned in tag. NO COMPLETION CCL (error 40) is returned. File number returned is in filenum. No I/O operation is canceled. WAIT for any I/O completion on filenum. COMPLETION File number is returned in filenum.
AWAITIO[X] Procedures Guardian Procedure Calls (A-B) Figure 2-1. AWAITIO[X] Operation Call AWAITIO[X] >-1 Particular File -1 filenum Any File Y Y <-1 Completion? N Y CCL = 40 0D timeout (Check) ? N Completion Wait timeoutfor Completion Bad Parameter Value CCL = 22 Any Completion ? N 0D timeout (Check) ? Y CCL = 40 N Waittimeout for Any Completion Completion Timeout CCL = 40 Timeout CCL = 40 VST002.
Guardian Procedure Calls (A-B) AWAITIO[X] Procedures Related Programming Manual For programming information about the AWAITIO[X] file-system procedures, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (A-B) BACKSPACEEDIT Procedure BACKSPACEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (A-B) BACKSPACEEDIT Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. input filenum INT:value is the number that identifies the open file on which the operation is to be performed. Related Programming Manual For programming information about the BACKSPACEEDIT procedure, refer to the Guardian Programmer’s Guide.
BINSEM_CLOSE_ Procedure Guardian Procedure Calls (A-B) BINSEM_CLOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manuals Summary The BINSEM_CLOSE_ procedure closes access to a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_CLOSE_ Procedure 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.
Guardian Procedure Calls (A-B) BINSEM_CREATE_ Procedure BINSEM_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations for Binary Semaphores Considerations Example Related Programming Manuals Summary The BINSEM_CREATE_ procedure creates, opens, and locks a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_CREATE_ Procedure segment (PFS) has reached the maximum limit of available space. The corresponding errno value is EMFILE. 4028 No space. The processor has reached the maximum limit of space available for binary semaphores. The corresponding errno value is ENOSPC. output semid INT (32) .EXT:ref:1 returns the binary semaphore ID. input security INT:value specifies the binary semaphore security.
Guardian Procedure Calls (A-B) • • • BINSEM_CREATE_ Procedure Unlocked. A binary semaphore can have no lock on it. Forsaken. A binary semaphore can be forsaken if it was locked by a process that has terminated. Binary semaphore operations Operations on a binary semaphores are atomic: they finish one at a time and never finish concurrently. The following procedures perform operations on binary semaphores: • • • • • • • BINSEM_CREATE_ which creates, opens, and locks a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_CREATE_ Procedure Related Programming Manuals For programming information about the BINSEM_CREATE_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (A-B) BINSEM_FORCELOCK_ Procedure BINSEM_FORCELOCK_ Procedure Summary Syntax for C Programmers Parameters 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.
Guardian Procedure Calls (A-B) BINSEM_FORCELOCK_ 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. input semid INT (32):value specifies the binary semaphore ID. processhandle output INT .
Guardian Procedure Calls (A-B) BINSEM_FORCELOCK_ Procedure Related Programming Manuals For programming information about the BINSEM_FORCELOCK_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (A-B) BINSEM_LOCK_ Procedure BINSEM_LOCK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manuals Summary The BINSEM_LOCK_ procedure locks a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_LOCK_ Procedure specifies the binary semaphore ID. input timeout INT (32):value specifies how many hundredths of a second the procedure should wait for the binary semaphore to become unlocked. The maximum value is 2,147,483,647. A value of -1D causes the procedure to wait indefinitely. A value of 0D causes the procedure to return immediately to the calling process, regardless of whether the binary semaphore is locked. Considerations Note.
Guardian Procedure Calls (A-B) BINSEM_LOCK_ Procedure Call PROCESS_GETINFOLIST_ with the process list attribute (attribute code 15, bit <7>) to determine whether a process is on the binary semaphore list waiting to lock a binary semaphore. • For information about binary semaphores, see “General Considerations for Binary Semaphores” for the BINSEM_CREATE_ procedure.
Guardian Procedure Calls (A-B) BINSEM_OPEN_ Procedure BINSEM_OPEN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manuals Summary The BINSEM_OPEN_ procedure opens a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_OPEN_ Procedure set by the BINSEM_CREATE_ procedure. The corresponding errno value is EACCES. 4022 Invalid parameter. The processhandle parameter does not specify a process. A process that is being created or is terminating is treated as though it does not exist. The corresponding errno value is EINVAL. 4024 Process cannot open the binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_OPEN_ Procedure Related Programming Manuals For programming information about the BINSEM_OPEN_ procedure, refer to the Guardian Programmer’s Guide.
BINSEM_UNLOCK_ Procedure Guardian Procedure Calls (A-B) BINSEM_UNLOCK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manuals Summary The BINSEM_UNLOCK_ procedure unlocks a binary semaphore.
Guardian Procedure Calls (A-B) BINSEM_UNLOCK_ Procedure 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.
Guardian Procedure Calls (A-B) BREAKMESSAGE_SEND_ Procedure BREAKMESSAGE_SEND_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The BREAKMESSAGE_SEND_ procedure sends a break-on-device message to a specified process.
Guardian Procedure Calls (A-B) BREAKMESSAGE_SEND_ Procedure specifies the file number by which the receiving process identifies the open of the process that is sending the break-on-device message. input breaktag INT .EXT:ref:2 if present, specifies a user-defined value to be delivered in the break-on-device message. This value corresponds to the break tag value that can be supplied to an access method with SETPARAM function 3. If this parameter is omitted, 0 is used.
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 3-1.
Guardian Procedure Calls (C) Table 3-1.
Guardian Procedure Calls (C) CANCEL Procedure CANCEL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Condition Code Settings 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. Note.
Guardian Procedure Calls (C) CANCEL Procedure Parameters input filenum INT:value is the number of an open file whose oldest incomplete operation you want to cancel. 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.
Guardian Procedure Calls (C) CANCELPROCESSTIMEOUT Procedure CANCELPROCESSTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Related Programming Manual Summary The CANCELPROCESSTIMEOUT procedure cancels a process-time timer previously initiated by a call to the SIGNALPROCESSTIMEOUT procedure.
Guardian Procedure Calls (C) CANCELPROCESSTIMEOUT Procedure Related Programming Manual For programming information about the CANCELPROCESSTIMEOUT procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CANCELREQ Procedure CANCELREQ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Messages Related Programming Manual Summary The CANCELREQ procedure is used to cancel an incomplete operation, identified by a file number and tag, on a file opened for nowait I/O. The canceled operation might or might not have had effects. For disk files, the file position might or might not be changed.
Guardian Procedure Calls (C) CANCELREQ Procedure input tag INT(32):value is the tag value passed to the procedure that initialized the I/O operation. It identifies the operation to be canceled. Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that the operation was canceled. > (CCG) does not return from CANCELREQ.
Guardian Procedure Calls (C) CANCELTIMEOUT Procedure CANCELTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Related Programming Manual Summary The CANCELTIMEOUT procedure cancels an elapsed-time timer previously initiated by a call to the SIGNALTIMEOUT procedure.
Guardian Procedure Calls (C) CANCELTIMEOUT Procedure Related Programming Manual For programming information about the CANCELTIMEOUT procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CHANGELIST Procedure CHANGELIST Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Examples 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.
CHANGELIST Procedure Guardian Procedure Calls (C) Syntax for TAL Programmers CALL CHANGELIST ( filenum ,function ,parameter ); ! i ! i ! i Parameters input filenum INT:value is the one-word integer variable returned by the call to FILE_OPEN_ or OPEN that opened the line. input function INT:value is an integer value specifying what change is to be made: >= 0 changes the poll state bit.
Guardian Procedure Calls (C) CHANGELIST Procedure input parameter INT:value is an integer value used with the function value to specify what change is to be made.
Guardian Procedure Calls (C) CHECK^BREAK Procedure CHECK^BREAK Procedure Summary Syntax for C Programmers Sytax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CHECK^BREAK Procedure input file-fcb INT:ref:* identifies the file to be checked for BREAK. 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, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CHECK^FILE Procedure CHECK^FILE Procedure Summary Syntax for Native C Programs Syntax for TAL Programmers Parameters Considerations Example 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.
Guardian Procedure Calls (C) CHECK^FILE Procedure Parameters returned value retval INT returns a value for the requested operation. The operations and their associated return values are listed in Table 3-2 and Table 3-3. 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.
CHECK^FILE Procedure Guardian Procedure Calls (C) Considerations • • • • • During the execution of this procedure, the detection of any error causes the display of an error message and the process is aborted. This procedure is used to get the primary extent or secondary extent size of a file that is no greater than 65,535 pages. If the primary and secondary extent sizes are greater than 65,535, error 538 is returned. Table 3-2 contains operations that return values returned in retval.
Guardian Procedure Calls (C) CHECK^FILE Procedure Table 3-2. CHECK^FILE Operations That Return Values (page 2 of 5) operation State of File FILE^BREAKHIT Any retval 0 if the break hit bit is equal to 0 in the FCB. 1 if the break hit bit is equal to 1 in the FCB. The break hit bit is an internal indicator normally used only by the SIO procedures. Note: When using the break-handling procedures, do not use FILE^BREAKHIT to determine whether the BREAK key has been pressed.
CHECK^FILE Procedure Guardian Procedure Calls (C) Table 3-2. CHECK^FILE Operations That Return Values (page 3 of 5) operation State of File retval FILE^FILEINFO Open , where .<0:3> = File type: 0 = Unstructured 1 = Relative 2 = Entry-sequenced 3 = Key-sequenced 4 = EDIT 8 = Odd unstructured .<4:9> = Device type .<10:15>= Device subtype The device type and subtype are described in Appendix A, Device Types and Subtypes.
Guardian Procedure Calls (C) CHECK^FILE Procedure Table 3-2. CHECK^FILE Operations That Return Values (page 4 of 5) operation State of File retval FILE^PRINT^ERR^MSG Open 0 if no error message is to be printed upon detection of a fatal error in the file. 1 if an error message is to be printed. FILE^PROMPT Open Returns the interactive prompt character for the file in <9:15>.
CHECK^FILE Procedure Guardian Procedure Calls (C) Table 3-2. CHECK^FILE Operations That Return Values (page 5 of 5) State of File operation retval 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.
Guardian Procedure Calls (C) CHECK^FILE Procedure Table 3-3. CHECK^FILE Operations That Return Addresses (page 1 of 2) operation State of File ret-addr (for native callers) retval (for other callers) FILE^BWDLINKFCB Any Returns the address of the FCB pointed to by the backward link pointer within the FCB. This indicates the linked-to FCBs that need to be checkpointed after an OPEN^FILE or CLOSE^FILE call. FILE^DUPFILE Open Returns the word address of the duplicate file FCB.
CHECK^FILE Procedure Guardian Procedure Calls (C) Table 3-3. CHECK^FILE Operations That Return Addresses (page 2 of 2) operation State of File ret-addr (for native callers) retval (for other callers) FILE^OPENERSPID^ADDR Open Returns the word address within the FCB of the file opener’s PID. Valid only for Cseries 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.
Guardian Procedure Calls (C) CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ 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.
Guardian Procedure Calls (C) CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ Parameters input segment-id INT:value is the number by which the process chooses to refer to the extended data segment. Segment IDs are in the following ranges: 0-1023 can be specified by user processes. Other IDs are reserved for HP software. No process can supply a segment ID greater than 2047. input file-name INT .
Guardian Procedure Calls (C) CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ maximum size, and the underlying virtual memory is expanded dynamically as the user accesses various addresses within the extended data segment. When the user first accesses a portion of an extensible data segment for which the corresponding swap file extent hasn’t been allocated, the operating system allocates the extent.
Guardian Procedure Calls (C) CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ output error INT .EXT:ref:1 indicates the outcome of the call.
Guardian Procedure Calls (C) CHECKALLOCATESEGMENT Procedure (Superseded by SEGMENT_ALLOCATE_CHKPT_ between processors. An error is returned from ALLOCATESEGMENT on the backup. • Nonexisting temporary swap file If a shared segment is being allocated (pin-and-flags bits <3:2> not equal to 0), and a volume name only is supplied in the file-name parameter, then the complete file name of the temporary file created by CHECKALLOCATESEGMENT is returned.
Guardian Procedure Calls (C) CHECKCLOSE Procedure (Superseded by FILE_CLOSE_CHKPT_ Procedure ) 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.
Guardian Procedure Calls (C) CHECKCLOSE Procedure (Superseded by FILE_CLOSE_CHKPT_ Procedure ) if present, specifies magnetic tape disposition, as follows: tape-disposition.<13:15> 0 Rewind and unload, do not wait for completion 1 Rewind, take offline, 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 If omitted, 0 is used.
Guardian Procedure Calls (C) CHECKDEALLOCATESEGMENT Procedure (Superseded by 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.
Guardian Procedure Calls (C) CHECKDEALLOCATESEGMENT Procedure (Superseded by input flags INT:value if present, has the form: <0:14> Must be 0. <15> 1 Indicates that dirty pages in memory are not to be copied to the swap file (see the ALLOCATESEGMENT procedure). 0 Indicates that dirty pages in memory are to be copied to the swap file. If omitted, this parameter defaults to 0. output error INT .EXT:ref:1 indicates the outcome of the call.
Guardian Procedure Calls (C) CHECKDEALLOCATESEGMENT Procedure (Superseded by file are unpredictable. If the CHECKDEALLOCATESEGMENT call causes a purge of a temporary file, the system does not write the dirty pages (that is, pages that are being used) out to the file. If the flags parameter is missing, the default value of 0 is used.
Guardian Procedure Calls (C) CHECKDEFINE Procedure CHECKDEFINE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary This 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, refer to the Guardian Programmer’s Guide.
CHECKDEFINE Procedure Guardian Procedure Calls (C) • • • • If the named DEFINE does not exist in the primary at the time of the call, then CHECKDEFINE will cause deletion of the DEFINE of the given name in the backup process if one exists. Otherwise, the named DEFINE will be copied to the backup, replacing the backup’s version of the DEFINE if it has one.
Guardian Procedure Calls (C) CHECKMONITOR Procedure CHECKMONITOR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CHECKMONITOR Procedure 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.
Guardian Procedure Calls (C) CHECKOPEN Procedure (Superseded by FILE_OPEN_CHKPT_ Procedure ) 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.
Guardian Procedure Calls (C) CHECKOPEN Procedure (Superseded by FILE_OPEN_CHKPT_ Procedure ) Parameters With the exception of filenum, all of the input parameters to this procedure are ignored; the values that were specified when the primary process called OPEN or FILE_OPEN_ are used instead. The ignored parameters are described under the OPEN procedure.
Guardian Procedure Calls (C) CHECKOPEN Procedure (Superseded by FILE_OPEN_CHKPT_ Procedure ) If no error is returned in backerror, the operation must be completed by a call to AWAITIO in the primary process. If you specify the tag parameter, the value returned by AWAITIO is -29D; the returned count and buffer address are undefined. If the condition code CCL is returned by AWAITIO, the file is automatically checkclosed by the checkpointing facility.
CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure ) Guardian Procedure Calls (C) CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure ) <0:7> = 2 Takeover from primary process; then <8:15> = 0 Primary process stopped 1 Primary process abnormally ended 2 Primarys process processor failed 3 Primary process called CHECKSWITCH <0:7> = 3 Illegal parameter; then <8:15> = number of parameter in error (leftmost position = 1) stack-origin input INT:ref:* checkpoints the process’s data stack from stack-origin through the current tipof-stack location (‘S’)
Guardian Procedure Calls (C) • CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure ) Maximum checkpoint size The largest stack area or data item that can be checkpointed is 32,500 bytes. Additionally, the sum total of the sizes of the stack area and each checkpoint item, plus an allowance of 20 bytes for each item, should not exceed 32,500 bytes. An item in this context means either a data item (user-declared size) or a file synchronization block with varying sizes.
Guardian Procedure Calls (C) • CHECKPOINT Procedure (Superseded by CHECKPOINTX Procedure ) No segment is used if the segment in use at the time of the last checkpoint and the segment in use when the CHECKMONITOR or CHECKSWITCH procedure was called are both unavailable.
CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) Guardian Procedure Calls (C) CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) <0:7> = 2 CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) Takeover from primary; then <8:15> = 0 1 2 3 <0:7> = 3 Primary process stopped Primary process abnormally ended Primarys process processor failed Primary process called CHECKSWITCH Illegal parameter, then <8:15> = 1 Error in stack-origin parameter n > 1 Error in word [n-2] (see “Considerations”) stack-origin input INT:ref:* contains an address.
CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) Guardian Procedure Calls (C) . .
Guardian Procedure Calls (C) CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) For example: Figure 3-1. Illegal Parameter Location If status.<0:7> = 3 then status.
Guardian Procedure Calls (C) • CHECKPOINTMANY Procedure (Superseded by CHECKPOINTMANYX Procedure ) Takeovers and selectable segments The selectable segment put into use following takeover depends on several factors: • • • • The segment in use at the time of the last checkpoint is put into use if it is available; that is, the segment was allocated to the backup using the SEGMENT_ALLOCATE_CHKPT_ or CHECKALLOCATESEGMENT procedure and has not since been deallocated by the SEGMENT_DEALLOCATE_CHKPT_ or CHEC
Guardian Procedure Calls (C) CHECKPOINTMANYX Procedure CHECKPOINTMANYX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
CHECKPOINTMANYX Procedure Guardian Procedure Calls (C) Parameters returned value status INT returns a status word of the following form: <0:7> = 0 No error <0:7> = 1 No backup process or unable to communicate with backup process; then <8:15> = file-system error number <0:7> = 2 Takeover from primary process; then <8:15> = 0 1 2 3 <0:7> = 3 Primary process stopped Primary process abnormally ended Primarys process processor failed Primary process called CHECKSWITCH Illegal parameter; then <8:15>
Guardian Procedure Calls (C) [2] Is the file number. [3] (Is reserved.) [4] (Is reserved.) CHECKPOINTMANYX Procedure If the item is a data area: [0:1] Is the length in bytes. [2] Is the segment ID. (If it is -1, the address is in the stack or current segment.) [3:4] Is the extended address. Considerations • Checkpointing the stack Checkpointing the entire data stack has the effect of providing a restart point for the backup process.
Guardian Procedure Calls (C) CHECKPOINTMANYX Procedure procedure MYPROC is to be the base procedure for a stack checkpoint; you can obtain its stack address in a global pointer STACKBASE as follows: INT .STACKBASE; PROC SET_MYPROC_BASE; BEGIN INT .DUMMY; @STACKBASE := @DUMMY; CALL MYPROC; END; The stack-origin address (if you do not specify the value -3) designates the boundary between what is to be checkpointed with the stack and what is not.
Guardian Procedure Calls (C) CHECKPOINTMANYX Procedure When checkpointing a set of global variables, if the set is small enough, you can obtain their address and size using the PROCESS_GETINFOLIST_ procedure, items 108 and 109. Code that will only be run as a TNS process can use constants for addressing global variables and assume adjacency of variables.
Guardian Procedure Calls (C) CHECKPOINTMANYX Procedure The selectable segment put into use following takeover depends on several factors: • • • • • • The segment in use at the time of the last checkpoint is put into use if it is available; that is, the segment was allocated to the backup process using the SEGMENT_ALLOCATE_CHKPT_ or CHECKALLOCATESEGMENT procedure and has not since been deallocated by the SEGMENT_DEALLOCATE_CHKPT_ or CHECKDEALLOCATESEGMENT procedure.
Guardian Procedure Calls (C) • • • • CHECKPOINTMANYX Procedure The segment ID was equal to -1 and the address was in an extended data segment, but no selectable segment was in use at the time of the call to CHECKPOINTMANYX. The address was in the stack, but either the count was too large, the area was above the highest stack address, the area was beyond the end of the stack, or the area overlapped the area used by the CHECKMONITOR procedure.
Guardian Procedure Calls (C) CHECKPOINTX Procedure CHECKPOINTX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CHECKPOINTX Procedure Parameters returned value status INT returns a status word of the following form: <0:7> = 0 No error <0:7> = 1 No backup or unable to communicate with backup; then <8:15> = file-system error number <0:7> = 2 Takeover from primary process; then <8:15> = 0 1 2 3 <0:7> = 3 Primary process stopped Primary process abnormally ended Primarys process processor failed Primary process called CHECKSWITCH Illegal parameter; then <8:15> = number of paramete
Guardian Procedure Calls (C) CHECKPOINTX Procedure input bufferx-n STRING .EXT:ref:* is the address of the data area to be checkpointed. See “Considerations” for details. If bufferx-n is omitted, a file synchronization block is to be checkpointed and the file number is specified in the segment-idn parameter. input count-n INT(32):value contains the number of bytes to be checkpointed if bufferx-n is provided. If bufferx-n is omitted, this parameter is ignored.
Guardian Procedure Calls (C) • CHECKPOINTX Procedure To checkpoint starting from the origin of an arbitrary procedure, introduce a lower procedure to obtain its stack address. For example, assume a procedure MYPROC is to be the base procedure for a stack checkpoint; you can obtain its stack address in a global pointer STACKBASE as follows: INT .STACKBASE; PROC SET_MYPROC_BASE; BEGIN INT .
Guardian Procedure Calls (C) • CHECKPOINTX Procedure Use $LEN or an equivalent language function to determine the length of data items, and use this value in the count-n parameter. The lengths of some data items differ between a native process and a TNS process. When checkpointing a set of global variables, if the set is small enough, you can obtain their address and size using the PROCESS_GETINFOLIST_ procedure, items 108 and 109.
Guardian Procedure Calls (C) • • CHECKPOINTX Procedure Extended addresses must be relative; they cannot be absolute. Extended addresses cannot be in the user code space.
Guardian Procedure Calls (C) • CHECKPOINTX Procedure Parameter errors (status.<0:7> = 3): • • • • • • • • The file number is not open. The extended address is absolute. The extended address is in logical segment 1, 2, or 3 (code or library spaces); that is, not in a data segment or the stack. The segment ID was omitted or was equal to -1 and the address was in a selectable extended data segment, but no selectable segment was in use at the time of the call to CHECKPOINTX.
Guardian Procedure Calls (C) CHECKRESIZESEGMENT Procedure CHECKRESIZESEGMENT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Summary This 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, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CHECKRESIZESEGMENT Procedure Condition Code Settings < (CCL) is returned if the error parameter is missing or there is a bounds error on the error parameter. = (CCE) indicates any condition not set by CCL. > (CCG) is not returned from this procedure.
Guardian Procedure Calls (C) CHECKSETMODE Procedure CHECKSETMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Summary CHECKSETMODE 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, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) 80 Set system message modes. 117 Set TRANSID forwarding. 141 Enable/disable large transfers. 149 Set alternate key insertion locking. CHECKSETMODE Procedure output error INT .EXT:ref:1 the error that occurred on the operation. The following 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.
Guardian Procedure Calls (C) CHECKSWITCH Procedure CHECKSWITCH Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
CHECKSWITCH Procedure Guardian Procedure Calls (C) 2 3 Primarys process processor failed Primary process called CHECKSWITCH Note. The normal return from a call to CHECKSWITCH is to the statement following a call to the CHECKPOINT[MANY][X] procedure. The return corresponds to the latest call to CHECKPOINT[MANY][X] by the primary process in which its stack was checkpointed.
Guardian Procedure Calls (C) CHILD_LOST_ Procedure CHILD_LOST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CHILD_LOST_ Procedure Parameters returned value status INT indicates the result of the check. Valid values are: 0 Process or process pair is not lost 1 (reserved) 2 Parameter error 3 Bounds error 4 Process or process pair is lost 5 System message is not relevant (see message parameter, below) message:length input:input STRING .EXT:ref:*, INT:value is the status-change message that was received. The message process must be exactly length bytes long.
Guardian Procedure Calls (C) CHILD_LOST_ Procedure Considerations • • CHILD_LOST_ accepts both C-series and D-series format messages. For details about the formats of system messages, refer to the Guardian Procedure Errors and Messages Manual. CHILD_LOST_ determines whether a process has been lost by comparing the process or process pair designated in the system message with the process that is specified in the processhandle parameter.
Guardian Procedure Calls (C) CHILD_LOST_ Procedure Example status := CHILD_LOST_ ( sys^message:length, proc^handle ); Related Programming Manual For programming information about the CHILD_LOST_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CLOSE Procedure (Superseded by FILE_CLOSE_ Procedure ) 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.
Guardian Procedure Calls (C) CLOSE Procedure (Superseded by FILE_CLOSE_ Procedure ) 2 Rewind, leave online, do not wait for completion 3 Rewind, leave online, wait for completion 4 Do not rewind, leave online 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.
Guardian Procedure Calls (C) CLOSE Procedure (Superseded by FILE_CLOSE_ Procedure ) Related Programming Manuals For programming information about the CLOSE file-system procedure, refer to the Enscribe Programmer’s Guide.
Guardian Procedure Calls (C) CLOSE^FILE Procedure CLOSE^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CLOSE^FILE Procedure owner. Note that the first parameter to CLOSE^FILE is either common-fcb or file-fcb; one or the other can be passed. input file-fcb INT:ref:* identifies the file to be closed if the FCB is passed. If BREAK is owned for the file being closed, it is returned to its previous owner. Note that the first parameter to CLOSE^FILE is either common-fcb or file-fcb; one or the other can be passed.
CLOSE^FILE Procedure Guardian Procedure Calls (C) If you call CLOSE^FILE on the common FCB and if an error is encountered when closing one of the files, the resulting action depends on the setting of ABORT^XFERERR for that file. (ABORT^XFERERR is set by OPEN^FILE or SET^FILE.) If ABORT^XFERERR is true, the process abends. If ABORT^XFERERR is false, a file-system error is returned. In either case, the file in question and all remaining SIO files are closed.
Guardian Procedure Calls (C) CLOSEALLEDIT Procedure 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.
Guardian Procedure Calls (C) CLOSEEDIT Procedure (Superseded by CLOSEEDIT_ Procedure ) 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.
Guardian Procedure Calls (C) CLOSEEDIT Procedure (Superseded by CLOSEEDIT_ Procedure ) Related Programming Manual For programming information about the IOEdit procedures, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) CLOSEEDIT_ Procedure CLOSEEDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary The CLOSEEDIT_ procedure closes a specified file that was opened by the OPENEDIT or OPENEDIT_ procedure.
Guardian Procedure Calls (C) CLOSEEDIT_ Procedure if supplied and not equal to 0, causes CLOSEEDIT_ to not close the file through the file system, but to perform the rest of its normal operation. This makes it possible to keep the open file number for use in later processing. Related Programming Manual For programming information about the CLOSEEDIT_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (C) COMPLETEIOEDIT Procedure COMPLETEIOEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 should call COMPLETEIOEDIT. You must supply the output values returned by AWAITIO[X] as the input to COMPLETEIOEDIT.
Guardian Procedure Calls (C) COMPLETEIOEDIT Procedure is the number that identifies the open file of interest. count-transferred input INT:value supplies the value of count-transferred returned by AWAITIO[X], which gives the count of the number of bytes transferred in the I/O operation. input tag INT(32):value supplies the value of tag returned by AWAITIO[X], which gives the applicationdefined tag that was stored by the system when the I/O operation was initiated.
Guardian Procedure Calls (C) COMPRESSEDIT Procedure COMPRESSEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) COMPRESSEDIT Procedure input, output filenum INT .EXT:ref:1 specifies the file number of the open file to be copied into compressed form. It returns the file number of the new file. input start 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.
Guardian Procedure Calls (C) COMPUTEJULIANDAYNO Procedure COMPUTEJULIANDAYNO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
Guardian Procedure Calls (C) COMPUTEJULIANDAYNO Procedure input year INT:value is the Gregorian year (for example, 1984, 1985, ... ). The range for year is restricted from 1 through 10000. input month INT:value is the Gregorian month (1-12). input day INT:value is the Gregorian day of the month (1-31).
COMPUTETIMESTAMP Procedure Guardian Procedure Calls (C) COMPUTETIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The COMPUTETIMESTAMP procedure converts a Gregorian (common civil calendar) date and time into a 64-bit Julian timestamp.
Guardian Procedure Calls (C) COMPUTETIMESTAMP Procedure The range of the year is restricted from 1 through 10000. output errormask 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 the following bits contains a 1.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYLDEV_ Procedure (G-Series and H-Series RVUs Only) CONFIG_GETINFO_BYLDEV_ Procedure (G-Series and H-Series RVUs Only) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for common-info Considerations Summary The CONFIG_GETINFO_BYLDEV_ and CONFIG_GETINFO_BYNAME_ procedures obtain the logical and physical attributes of a device on a G-series RVU.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) #include __int32_t CONFIG_GETINFO_BYNAME_ ( char *devname , short length , short *common-info , short common-info-maxlen , short *common-info-len , char *specific-info , short specific-info-maxlen , short *specific-info-len , __int_32_t timeout , __int32_t *error-detail ); Syntax for TAL Programmers error := CONFIG_GETINFO_BYLDEV_ ( ldevnum ,common-info ,common-info-maxlen ,c
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) 2D Parameter error; error-detail contains the number of the first parameter found to be in error, where 1D designates the first parameter on the left. 3D Bounds error; error-detail contains the number of the first parameter found to be in error, where 1D designates the first parameter on the left.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) input common-info-maxlen INT:value specifies the length in bytes of the buffer pointed to by common-info. If the buffer length is too short for the full set of device attributes, the procedure sets error to 2D, sets error-detail to 3D, and does not return any information on the specified device. output common-info-len INT .EXT:ref:1 returns the actual length in bytes of the buffer pointed to by common-info.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) input timeout INT(32):value specifies how many hundredths of a second the procedure should wait for a response from the I/O subsystem. The maximum value is 2147483647. The default value is 6000D (one minute). A value of -1D causes the procedure to wait indefinitely. error-detail output INT(32) .EXT:ref:1 for some returned errors, contains additional information. See error, earlier in this subsection.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) In the TAL ZSYSTAL file, the structure of the buffer that the common-info parameter points to is defined as follows.
CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Guardian Procedure Calls (C) In the C zsysc file, the structure of the buffer that the common-info parameter points to is defined as follows.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Z^VERSION identifies the version of the ZSYS^DDL^CONFIG^GETINFO structure. The following TAL literal is defined in the ZSYSTAL file. Literals in the zsysc file, for C programs, are the same as those for TAL except that they contain the underscore (_) character instead of the circumflex (^) character.
CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Guardian Procedure Calls (C) Z^DEVICE^SUBTYPE is the device subtype of the device. See Appendix A, Device Types and Subtypes for a list of device subtypes. Z^LOGICAL^STATUS is the logical status of the device. The following TAL literals are defined in the ZCOMTAL file. Literals in the zcomc file, for C programs, are the same as those for TAL except that they contain the underscore (_) character instead of the circumflex (^) character.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Z^BACKUP^PHANDLE is the process handle of the backup I/O subsystem that owns the device. Z^RESERVED^1 is reserved. 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.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) The structure for magnetic disk and SCSI-IOP devices is defined in TAL as follows: STRUCT SCSI^DEVICE^INFO^DEF (*) FIELDALIGN (SHARED2); BEGIN STRUCT SPECIFIC^HDR; BEGIN INT VERSION; INT MAX^NUM^PATHS; INT PRIMARY^SUBTYPE; INT MIRROR^SUBTYPE; END; INT AUDITED; INT DEMOUNTABLE; INT RESERVE1; INT FLAGS; STRUCT PATH^INFO[0:3]; BEGIN STRUCT STANDARD; BEGIN INT CONFIGURED; INT INUSE; INT STATE; INT RESERVED; INT(32)
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) The structure for tape devices is defined in TAL 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; FILL
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) 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.
Guardian Procedure Calls (C) 3 MOUNT 4 REVIVE 5 (reserved) 6 EXERCISE 7 EXCLUSIVE 8 HARD DOWN 9 UNKNOWN CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) group All objects accessible to a pair of service processors in a system enclosure. In a NonStop S-series server, a group includes all components in a system enclosure. The valid range is from 1 through 999. module A set of components that shares a hardware interconnection. A module is a subset of a group.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) scsiTargetId The SCSI ID of the Open SCSI device. This is the address used by the Open SCSI I/O process to access the device. More information about the definition of the specific_info field for the Storage subsystem can be found in the Guardian file $SYSTEM.ZSPIDEF.ZSTOTAL.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) The return structure and its substructures are defined in TAL as follows: Struct Sm_Lif_GetInfo_Template( * ); Begin Int(32) lif_state ! i.e. started, stopped. Int(32) access_state; ! Access to network.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) access_state Indicates whether there is at least one processor with a data path through the PIF associated with the specified LIF. A value of 2 (UP) indicates at least one processor with a data path. A value of 1 (DOWN) indicates that there is no data path. Lif_Potential_Access_Template Lists processors that potentially can have a data path through the PIF associated with the specified LIF.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) use SWAN, null values are returned in this structure. This structure definition can be found in the TAL ZWANTAL file.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME_ Procedure (G-Series and H-Series RVUs Only) Z^CLIPNUM is the clip number that identifies which clip number is being used. The valid range for the clip number is 1 through 3. Z^UNIT is reserved. It is redefined by Z^LINENUM. Z^LINENUM identifies the line number (0 or 1) on a clip that is being used. Z^CPU is the processor that is currently being used to run the LINE. The LINE is a Subsystem Programmatic Interface (SPI) object in a subsystem.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYLDEV2_ Procedure (G-Series and H-Series RVUs Only) CONFIG_GETINFO_BYLDEV2_ Procedure (G-Series and H-Series RVUs Only) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for common-info Considerations Summary The CONFIG_GETINFO_BYLDEV2_ and CONFIG_GETINFO_BYNAME2_ procedures obtain the logical and physical attributes of a device on a G-series RVU.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) 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.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) 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
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) ldevnum (CONFIG_GETINFO_BYLDEV2_ only) input INT(32):value specifies the logical device number of the device for which information is requested. devname:length (CONFIG_GETINFO_BYNAME2_ only) input: input STRING .EXT:ref:*, INT:value specifies the name of the device to look up. The devname parameter and the length parameter are required. The length parameter is the length of the string in bytes.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) input common-maxlen INT:value specifies the length in bytes of the buffer pointed to by common-info. This value must be greater than or equal to the size of common-info; otherwise, error is set to 2 and error-detail is set to 3. output common-len INT .EXT:ref:1 number of bytes returned by common-info. If the value returned by this procedure is nonzero, this parameter will be returned as zero.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) input timeout INT(32):value specifies how many hundredths of a second the procedure should wait for a response from the device. If zero is passed, the timeout value is set to its default (6000D or 1 minute). If -1D is passed, the procedure does not time out. error-detail output INT(32) .EXT:ref:1 If error-detail is not 0, then an error-dependent value is returned.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) In the TAL ZSYSTAL file, the structure of the buffer that the common-info parameter points to is defined as follows.
CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) Guardian Procedure Calls (C) In the C zsysc file, the structure of the buffer that the common-info parameter points to is defined as follows.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) Z^VERSION identifies the version of the ZSYS^DDL^CONFIG^GETINFO structure. The following TAL literal is defined in the ZSYSTAL file. Literals in the zsysc file, for C programs, are the same as those for TAL except that they contain the underscore (_) character instead of the circumflex (^) character.
CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) Guardian Procedure Calls (C) Name (ZCOM^VAL^ ) Value Indicates the I/O subsystem is SUMSTATE^STOPPING 6 Stopping SUMSTATE^SUSP 7 Suspended SUMSTATE^UNKWN 8 In an unknown state SUMSTATE^SUSPENDIN G 9 Suspending SUMSTATE^SERVICE 10 Being serviced Z^CONFIG^NAME^LEN is the length of the configured name of the device, which is in Z^CONFIG^NAME. Z^CONFIG^NAME is the configured name of the device.
Guardian Procedure Calls (C) CONFIG_GETINFO_BYNAME2_ Procedure (G-Series and H-Series RVUs Only) 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 Guardian Procedure Calls (C) 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.
Guardian Procedure Calls (C) [6] 0.01 second CONTIME Procedure (0-99) input t0, t1, t2 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).
CONTROL Procedure Guardian Procedure Calls (C) CONTROL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Control Operations Considerations Related Programming Manuals Summary CONTROL is used to perform device-dependent I/O operations.
Guardian Procedure Calls (C) CONTROL Procedure input operation INT:value is a value that defines an operation to be performed (see Table 3-4 and Table 3-5 for a list of operation numbers). input param INT:value is the value of an operation being performed (see Table 3-4 and Table 3-5). input tag 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.
CONTROL Procedure Guardian Procedure Calls (C) Control Operations Table 3-4 and Table 3-5 list the CONTROL operations that can be used with the I/O devices discussed in this manual for NonStop servers. Table 3-4 describes CONTROL operation 1 only; Table 3-5 describes the remaining CONTROL operations. Table 3-4.
Guardian Procedure Calls (C) CONTROL Procedure Table 3-4.
CONTROL Procedure Guardian Procedure Calls (C) Table 3-4.
Guardian Procedure Calls (C) CONTROL Procedure Table 3-5. CONTROL Operations 2 Through 27 (page 1 of 3) Operation Description Description of 2 Write end of file on unstructured disk or magnetic tape (if disk, write access is required). None 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.
CONTROL Procedure Guardian Procedure Calls (C) Table 3-5. CONTROL Operations 2 Through 27 (page 2 of 3) Operation Description Description of 21 Disk, allocate or deallocate extents (write access is required). 0 deallocate all extents past the end-of-file extent 1:maximum-extents number of extents to allocate for a nonpartitional file (for DP2 disk files only) 1:16*number of partitions number of extents to allocate for a partitioned file 22 Cancel an AM3270 I/O operation.
Guardian Procedure Calls (C) CONTROL Procedure Table 3-5. CONTROL Operations 2 Through 27 (page 3 of 3) Operation Description Description of 26 Requests immediate completion of all outstanding I/O requests without loss of data by the recipient of the CONTROL 26 request. None 27 Wait for DP2 disk file write. This operation is not supported for queue files. This operation finishes when a WRITE, WRITEUPDATE, or WRITEUPDATEUNLOCK occurs on a DP2 disk file designated by filenum.
Guardian Procedure Calls (C) CONTROL Procedure Considerations • Nowait and CONTROL If the CONTROL procedure is used on a file that is opened nowait, it must be completed with a call to the AWAITIO procedure. • Disk files • Writing EOF to an unstructured file Writing EOF to an unstructured disk file sets the EOF pointer to the relative byte address indicated by the setting of the next-record pointer and writes the new EOF setting in the file label on disk.
Guardian Procedure Calls (C) • CONTROL Procedure Interprocess communication • Nonstandard operation and parameter values Any value can be specified for the operation and parameter parameters. An application-defined protocol should be established for interpreting nonstandard parameter values.
Guardian Procedure Calls (C) CONTROLBUF Procedure 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.
Guardian Procedure Calls (C) CONTROLBUF Procedure is the number of an open file. It identifies the file on which the CONTROLBUF procedure performs an I/O operation. input operation INT:value is a value defined by the device, such as: 1 = Load DAVFU (printer subtype 4) input buffer INT:ref:* is an array that contains the information to be used for the CONTROLBUF operation. input count INT:value is the number of bytes contained in buffer.
Guardian Procedure Calls (C) CONTROLBUF Procedure 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. A count of the number of bytes transferred is obtained by the count-transferred parameter of the AWAITIO procedure when the I/O finishes.
Guardian Procedure Calls (C) CONTROLMESSAGESYSTEM Procedure CONTROLMESSAGESYSTEM Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The CONTROLMESSAGESYSTEM procedure controls the maximum number of receive and send messages used by a process.
CONTROLMESSAGESYSTEM Procedure Guardian Procedure Calls (C) input value INT:value supplies a value to be used in taking an action. See the following list of action codes and values. action code value action taken 0 14095 This value (considered an unsigned number) sets the limit on the number of outstanding incoming messages to the process. The default limit is 255; opening $RECEIVE with receive depth can increase this limit.
Guardian Procedure Calls (C) CONTROLMESSAGESYSTEM Procedure operating system, reserving message-system control blocks is no longer applicable, and the secondary functions of the procedure are accomplished by calling CONTROLMESSAGESYSTEM. Although RESERVELCBS no longer performs any function, it can still be called without error.
Guardian Procedure Calls (C) CONVERTASCIIEBCDIC Procedure CONVERTASCIIEBCDIC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary This procedure translates the 256 EBCDIC encodings to and from the 256 8-bit ASCII encodings. For more information, refer to Appendix K, Character Set Translation.
Guardian Procedure Calls (C) CONVERTASCIIEBCDIC Procedure All other values have undefined effects.
Guardian Procedure Calls (C) CONVERTPROCESSNAME Procedure (Superseded by FILENAME_RESOLVE_ CONVERTPROCESSNAME Procedure (Superseded by FILENAME_RESOLVE_ 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. The CONVERTPROCESSNAME procedure converts a process name from local to network form.
Guardian Procedure Calls (C) CONVERTPROCESSTIME Procedure 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.
Guardian Procedure Calls (C) CONVERTPROCESSTIME Procedure output hours INT:ref:1 returns the hours portion of the value of process-time specified. output minutes INT:ref:1 is the minutes portion of the value of process-time specified. output seconds 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.
Guardian Procedure Calls (C) CONVERTTIMESTAMP Procedure CONVERTTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CONVERTTIMESTAMP Procedure julian-timestamp input FIXED:value is a four-word Julian timestamp to be converted. input direction INT:value indicates what time form or timestamp to return. You can specify one of the following values for direction. 0 1 2 3 GMT to LCT GMT to LST LCT to GMT LST to GMT If direction is omitted, 0 is used. If direction is out of range, a value of -3 is returned in error.
Guardian Procedure Calls (C) • CONVERTTIMESTAMP Procedure 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).
CONVERTTIMESTAMP Procedure Guardian Procedure Calls (C) It is vital to add at least one period of nonzero DST offset to the DST table, to avoid CONVERTTIMESTAMP reporting error 2 (DST table not loaded). In addition to the accurate table entries recommended above, it is good practice to add fictitious entries to the DST table, to avoid CONVERTTIMESTAMP reporting error 1 (DST range error) when it converts times earlier than expected or later than expected.
Guardian Procedure Calls (C) CONVERTTIMESTAMP Procedure It is particularly important to avoid abending or other extreme actions when responding to errors in time conversions that might be several years in the past or the future. It is difficult for operators of a computer system to provide accurate information about future and past Daylight Saving Time data. Example #include #include /* define long long etc.
Guardian Procedure Calls (C) CPU_GETINFOLIST_ Procedure CPU_GETINFOLIST_ Procedure Use the PROCESSOR_GETINFOLIST_ Procedure instead of CPU_GETINFOLIST_. Calls to PROCESSOR_GETINFOLIST_ are identical in their format and values to those for CPU_GETINFOLIST_.
Guardian Procedure Calls (C) CPUTIMES Procedure 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 the following 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
CPUTIMES Procedure Guardian Procedure Calls (C) Syntax for TAL Programmers CALL CPUTIMES ( [ ,[ ,[ ,[ ,[ ,[ cpu ] sysid ] total-time ] cpu-process-busy ] cpu-interrupt ] cpu-idle ] ); ! ! ! ! ! ! i i o o o o Parameters input cpu INT:value specifies the processor number of a processor in the system. The default is the local processor. input sysid INT:value specifies the system number. The default is the local system.
Guardian Procedure Calls (C) CPUTIMES Procedure Condition Code Settings < (CCL) indicates that the system is in one of the following states: • • • Unavailable. Does not exist. The procedure could not get resources to execute. = (CCE) indicates that CPUTIMES is successful. > (CCG) indicates that supplied parameters failed the bounds check.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) 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.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Parameters input, output file-name INT:ref:12 is an array containing the internal-format file name of the disk file to be created.
CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Guardian Procedure Calls (C) secondary-extentsize input INT:value is the size of the secondary extents in pages (one page is 2048 bytes). (The maximum number of secondary extents that a file can have allocated is maximumextents - 1. See maximum-extents, below.) The maximum value of secondary-extentsize is 65535 (134,215,680 bytes). If omitted, the size of the primary extent is used for the secondary extent size.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) input recordlen INT:value is the maximum length of the logical record in bytes. If omitted, 80 is used. This parameter is ignored for unstructured files.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) partition-params input INT:ref:* is an array containing parameters that describe this file. It applies only if the file is a multivolume file. If the file is to span multiple volumes, this parameter is required; otherwise, you can omit it. If included, and you do not want partitions, the first word must be 0. See “Considerations” for the format of this array.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Condition Code Settings < (CCL) indicates that the CREATE failed (call FILEINFO or FILE_GETINFO_ ). = (CCE) indicates that the file was created successfully. > (CCG) indicates that the device is not a disk. Considerations • key-sequenced-params array format Word[0] key-len Word[1] key-offset Word[2] index-block-len key-len (INT:value) is the length, in bytes, of the record’s primary-key field.
CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Guardian Procedure Calls (C) nf-alt-files a 1-byte value, specifies the number of alternate-key files for this primary file. nk-alt-keys a 1-byte value, specifies the number of alternate-key fields in this primary file.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) a 1-byte value, is used to specify a null value if key-attributes.<0> is equal to 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.
CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Guardian Procedure Calls (C) • partition-params array format Number of Words [1] num-of-extra-partitions $volname or \sysnumvolname for partition 1 $volname or \sysnumvolname for partition 2 [4] : $volname or \sysnumvolname for partition n primary-extent-size part 1 [1] : primary-extent-size part n [1] secondary-extent-size part 1 secondary-extent-size part n This sequence must be included in the partition-parameters array for keyseque
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) primary-extent-size (INT:value) is the size of the primary extent for the particular partition. secondary-extent-size (INT:value) is the size of the secondary extents for the particular partition. Specifying 0 results in the primary-extent-size value being used.
Guardian Procedure Calls (C) • CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Upper limit for maximum-extents There is no guarantee that a file will be created successfully if you specify a value greater than 500 for maximum-extents.
Guardian Procedure Calls (C) • CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) Insertion-ordered alternate keys All of the non-unique alternate keys of a file must have the same duplicate key ordering attribute. That is, a file may not have both insertion-ordered alternate keys and standard (duplicate ordering by primary key) non-unique alternate keys.
Guardian Procedure Calls (C) CREATE Procedure (Superseded by FILE_CREATELIST_ Procedure ) 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 file-system procedure, refer to the Enscribe Programmer’s Guide.
Guardian Procedure Calls (C) CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ 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.
Guardian Procedure Calls (C) CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ Parameters process-name output INT:ref:3 is an array where a system-generated process name returns. The process-name parameter is of the form: $zaaaa where “z” is the letter Z, Y, or X. “a” represents an alphanumeric character except “o” and “i.” CREATEPROCESSNAME ensures that the character position after the last “a” is a blank.
Guardian Procedure Calls (C) CREATEPROCESSNAME Procedure (Superseded by PROCESSNAME_CREATE_ If a standard temporary file name is used, the file is purged when the first process closes it because there are no other opens for the file. The second process is then unable to access the file. An example of using CREATEPROCESSNAME: INT .TEMP^FNAME[0:11] := ["$VOL1 ", 9 * [" "]]; . . CALL CREATEPROCESSNAME ( TEMP^FNAME[4] ); ! returns $zddd TEMP^FNAME[4].
Guardian Procedure Calls (C) CREATEREMOTENAME Procedure (Superseded by PROCESSNAME_CREATE_ 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.
Guardian Procedure Calls (C) CREATEREMOTENAME Procedure (Superseded by PROCESSNAME_CREATE_ Parameters output name INT:ref:3 is an array where CREATEREMOTENAME returns a system-generated process name (in local form) that is unique for the designated system. The name parameter is of the form: $zaaaa where “z” is the letter Z, Y, or X. “a” represents an alphanumeric character except “o” and “i.” CREATEREMOTENAME ensures that the character position after the last “a” is a blank.
Guardian Procedure Calls (C) • CREATEREMOTENAME Procedure (Superseded by PROCESSNAME_CREATE_ Remote system DCT The creation of a process name does not create a process or make an entry in the remote system’s DCT.
Guardian Procedure Calls (C) CREATORACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ CREATORACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (C) CREATORACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ For a given process, an access ID is a word in the process control block (PCB) that contains a group number in the left byte and a member number in the right byte. There are two access IDs. The creator access ID (CAID) is returned from the CREATORACCESSID procedure and identifies the user who created the process.
Guardian Procedure Calls (C) CRTPID_TO_PROCESSHANDLE_ Procedure CRTPID_TO_PROCESSHANDLE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The CRTPID_TO_PROCESSHANDLE_ procedure converts a process ID (CRTPID) to the corresponding process handle. Refer to Appendix D, File Names and Process Identifiers for information about process IDs and process handles.
Guardian Procedure Calls (C) CRTPID_TO_PROCESSHANDLE_ Procedure processhandle output INT .EXT:ref:10 returns the process handle of the process designated by process-id. output pair-flag 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.
Guardian Procedure Calls (C) CURRENTSPACE Procedure (Superseded) CURRENTSPACE Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (C) CURRENTSPACE Procedure (Superseded) ascii-space-id output STRING:ref:5 is an ASCII string in the form: map.<#> where map is one the following: UC indicates user code UL indicates user library SC indicates system code SL indicates system library <#> is the octal space number in ASCII. for example: UC.01 or SL.33 Related Programming Manual For information about the CURRENTSPACE procedure, refer to 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 4-1 lists all the procedures in this section. Table 4-1.
Guardian Procedure Calls (D-E) DAYOFWEEK Procedure Table 4-1.
Guardian Procedure Calls (D-E) DEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_ Syntax for TAL Programmers day := DAYOFWEEK ( julian-day-num ); ! i Parameters returned value day INT is the code for the day of week, as follows: 0 = Sunday, 1 = Monday, ..., 6 = Saturday. If day is -1, then the julian-day-num was negative. julian-day-num INT(32):value contains the Julian Day Number for which the day of the week is desired. Example INT day INT(32) JDN := 2435012D; . .
Guardian Procedure Calls (D-E) DEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_ 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. Syntax for C Programmers This procedure does not have a C syntax, because it is superseded and should not be used for new development.
Guardian Procedure Calls (D-E) DEALLOCATESEGMENT Procedure (Superseded by SEGMENT_DEALLOCATE_ 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 • The flags parameter The flags.
Guardian Procedure Calls (D-E) DEBUG Procedure 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.
Guardian Procedure Calls (D-E) • • • Starting the process from the command interpreter. While the process is executing, press the BREAK key. The command interpreter returns to the command input mode. Find the cpu,pin of the process, and type in DEBUG cpu,pin. Specifying a breakpoint when a process is in the debug state. When that breakpoint is hit, the process enters the debug state. You can use the Inspect debugger by setting the Inspect attribute associated with a process.
Guardian Procedure Calls (D-E) DEBUG Procedure Only program file owners and users with appropriate privileges are able to debug programs that set the user ID. Related Programming Manual For information about the Debug facility, refer to the Debug Manual. For information about the Inspect debugger, refer to the Inspect Manual.
Guardian Procedure Calls (D-E) DEBUGPROCESS Procedure (Superseded by PROCESS_DEBUG_ Procedure ) 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.
Guardian Procedure Calls (D-E) DEBUGPROCESS Procedure (Superseded by PROCESS_DEBUG_ Procedure ) [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 Note that the process ID can be in a timestamp or a local or remote named format. output error INT:ref:1 returns a file-system error number indicating the outcome of the process debug attempt.
Guardian Procedure Calls (D-E) DEBUGPROCESS Procedure (Superseded by PROCESS_DEBUG_ Procedure ) input now INT:value The caller’s process access ID (PAID) must be the super ID (255, 255) to use this parameter. If you supply 1, the process should be debugged immediately (even if it is currently executing privileged code). If omitted, the normal debug sequence is executed. Considerations DEBUGPROCESS cannot be used on a high-PIN unnamed process.
DEFINEADD Procedure Guardian Procedure Calls (D-E) DEFINEADD Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary This procedure adds a DEFINE to the calling process’s context using the attributes in the working set. It can be used to replace an existing DEFINE with the attributes in the working set.
Guardian Procedure Calls (D-E) DEFINEADD Procedure 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. 2059 Working set is invalid 2066 Missing parameter 2069 The DEFMODE of the process does not permit the addition of the DEFINE For other error values associated with DEFINEs, refer to the Guardian Procedure Errors and Messages Manual.
DEFINEADD Procedure Guardian Procedure Calls (D-E) Example STRING .EXT define^name[0:23]; . . define^name ':=' ["=mydefine error := DEFINEADD( define^name, 1 ); IF error <> DEOK THEN ... ; "]; Related Programming Manual For programming information about the DEFINEADD procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (D-E) DEFINEDELETE Procedure DEFINEDELETE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary This procedure allows the caller to delete a DEFINE from the calling process’s context.
DEFINEDELETE Procedure Guardian Procedure Calls (D-E) input define-name STRING .EXT:ref:24 is the 24-byte array that contains the name of the DEFINE to be deleted. The name is left-justified and padded on the right with blanks. Trailing blanks are ignored. 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’s context occurs.
Guardian Procedure Calls (D-E) DEFINEDELETEALL Procedure DEFINEDELETEALL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Considerations Related Programming Manual Summary This procedure allows the caller to delete all DEFINEs from the calling process’s context. Syntax for C Programmers #include short DEFINEDELETEALL (); Syntax for TAL Programmers CALL DEFINEDELETEALL; Considerations • • • If an error occurs, the DEFINE is not deleted.
Guardian Procedure Calls (D-E) DEFINEINFO Procedure DEFINEINFO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary This procedure returns selected information about a DEFINE.
DEFINEINFO Procedure Guardian Procedure Calls (D-E) 2066 Parameter missing For other error values associated with DEFINEs, refer to the Guardian Procedure Errors and Messages Manual. input define-name STRING .EXT:ref:24 is the 24-byte array that contains the name of the DEFINE to be used by the procedure. The name is left-justified and padded on the right with blanks. Trailing blanks are ignored. output class STRING .
Guardian Procedure Calls (D-E) DEFINEINFO Procedure output value-len INT:ref:1 gives the actual size of the external representation for the value. If greater than value-buf-len, then only value-buf-len bytes have been transferred and truncation has occurred. An absent attribute is indicated by a length of -1. Considerations This 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 .
DEFINELIST Procedure Guardian Procedure Calls (D-E) 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.
Guardian Procedure Calls (D-E) DEFINELIST Procedure Parameters input filenum INT:value is the name of the one-word integer variable specified in the call to FILE_OPEN_ or OPEN that opened the line.
Guardian Procedure Calls (D-E) DEFINELIST Procedure For tributary stations, this parameter has no functional effect; a dummy argument must still be supplied, however, for each station except Envoy’s multipoint tributary. In this case, the polling-type can be: 0 RVI (reverse interrupt) 1 WACK (wait for acknowledgment) 2 NAK (negative acknowledge) Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO).
Guardian Procedure Calls (D-E) DEFINEMODE Procedure DEFINEMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary This 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.
Guardian Procedure Calls (D-E) DEFINEMODE Procedure output old-value INT:ref:1 if present, returns the previous status of the DEFINE mode: 0 (OFF) or 1 (ON). 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.
Guardian Procedure Calls (D-E) DEFINENEXTNAME Procedure DEFINENEXTNAME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary This procedure returns the name of the DEFINE that follows the specified DEFINE (in ASCII order).
Guardian Procedure Calls (D-E) DEFINENEXTNAME Procedure input, output define-name STRING .EXT:ref:24 on input, is a DEFINE name. It need not name an existing DEFINE. The name must be left-justified and padded on the right with blanks. Trailing blanks are ignored. on output, is the name of the DEFINE following the input DEFINE name in the process context (in ASCII order); if define-name is blank on input, the name of the first DEFINE is returned.
Guardian Procedure Calls (D-E) DEFINEPOOL Procedure (Superseded by POOL_* Procedures) DEFINEPOOL Procedure (Superseded by POOL_* Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. *POOL procedures are replaced by POOL_* procedures. There is no one-for-one replacement.
Guardian Procedure Calls (D-E) 1 2 3 4 5 6 DEFINEPOOL Procedure (Superseded by POOL_* Procedures) Bounds error on pool-head Bounds error on pool Invalid pool-size pool-head and pool overlap. pool-head is not word-aligned. pool is not word-aligned. output pool-head INT .EXT:ref:19 is a 19-word array to be used as the pool header; GETPOOL and PUTPOOL use this array to manage the pool. An even-byte address must be specified. input pool INT .
Guardian Procedure Calls (D-E) DEFINEPOOL Procedure (Superseded by POOL_* Procedures) initialize a 19-word array, the pool-header, that is used to manage the pool. The pool and the pool header can reside in the user data stack or in extended memory. The pool routines accept and return extended addresses that apply to both the stack and extended memory.
Guardian Procedure Calls (D-E) DEFINEPOOL Procedure (Superseded by POOL_* Procedures) Although they can also be used to manage the allocation of a collection of equalsized blocks, these procedures are not recommended for that purpose, because they can consume more processor time and pool memory than user-written routines designed for that specific task.
Guardian Procedure Calls (D-E) DEFINEREADATTR Procedure DEFINEREADATTR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary This procedure allows the caller to obtain the current value of an attribute in a DEFINE in the calling process’s 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.
Guardian Procedure Calls (D-E) DEFINEREADATTR Procedure Parameters returned value error INT indicates the outcome of the call: 0 2049 2051 2052 2054 2055 2061 2066 Successful A syntax error occurred in name DEFINE not found An error occurred when placing PFS in use Bounds error on parameter Attribute not supported No more attributes (see “Considerations”) Missing parameter For other error values associated with DEFINEs, refer to the Guardian Procedure Errors and Messages Manual.
Guardian Procedure Calls (D-E) DEFINEREADATTR Procedure output value-buf STRING .EXT:ref:* is the data array provided by the calling program to return the value of the attribute. The value is in external form, suitable for display. If the value is a file name, it is fully qualified. input value-buf-len INT:value is the length of the array value-buf in bytes. output value-len INT:ref:1 gives the actual size of the external representation for the value.
Guardian Procedure Calls (D-E) • • • • • • • • DEFINEREADATTR Procedure If an error occurs, the contents of the data array are undefined. Both attribute-name and cursor can be present. If cursor is present, it is used to “name” the attribute whose value is to be returned, and attribute-name returns the name of the attribute. When the cursor parameter is used, parameter info-word is returned even though the attribute can be absent from the DEFINE working set.
Guardian Procedure Calls (D-E) DEFINERESTORE Procedure DEFINERESTORE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary DEFINERESTORE 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.
Guardian Procedure Calls (D-E) DEFINERESTORE Procedure 2054 Bounds error on buffer, define-name or checknum parameter 2055 Illegal attribute in saved DEFINE 2057 DEFINE or working set is incomplete. A required attribute is missing. 2058 DEFINE or working set is inconsistent. Two or more attributes have conflicting values. The checknum parameter identifies the consistency check that failed.
Guardian Procedure Calls (D-E) DEFINERESTORE Procedure output define-name 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. output checknum INT:ref:1 if present, and the DEFINE is inconsistent, contains the number of the consistency check that failed.
Guardian Procedure Calls (D-E) DEFINERESTOREWORK[2] Procedures DEFINERESTOREWORK[2] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary DEFINERESTOREWORK 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. DEFINERESTOREWORK2 allows a second background working set, saved by DEFINESAVEWORK2, to be restored.
Guardian Procedure Calls (D-E) DEFINERESTOREWORK[2] Procedures Related Programming Manual For programming information about the DEFINERESTOREWORK[2] procedures, refer to the Guardian Programmer’s Guide.
DEFINESAVE Procedure Guardian Procedure Calls (D-E) DEFINESAVE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary DEFINESAVE 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.
Guardian Procedure Calls (D-E) DEFINESAVE Procedure 2054 Bounds error on buffer, deflen or define-name parameters 2057 DEFINE or working set is incomplete. A required attribute is missing. 2058 DEFINE or working set is inconsistent. Two or more attributes have conflicting values. The checknum parameter of the DEFINEADD procedure identifies the consistency check that failed. 2059 DEFINE or working set is invalid 2066 Parameter missing 2075 option.
Guardian Procedure Calls (D-E) DEFINESAVE Procedure <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. Considerations • • • • The DEFINE saved in buffer is in internal form. You should not modify it. If you change it in any way, DEFINE RESTORE might not be able to restore it.
Guardian Procedure Calls (D-E) DEFINESAVEWORK[2] Procedure DEFINESAVEWORK[2] Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary DEFINESAVEWORK saves the DEFINE working set in the background set. DEFINESAVEWORK2 allows a second background working set to be saved.
Guardian Procedure Calls (D-E) DEFINESETATTR Procedure DEFINESETATTR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary This 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.
Guardian Procedure Calls (D-E) 2052 Unable to obtain file-system buffer space 2055 Attribute not supported 2062 Attribute name too long 2063 A syntax error occurred in default names 2064 The required attribute cannot be reset 2066 Missing parameter 2067 Illegal value DEFINESETATTR Procedure For other error values associated with DEFINEs, refer to the Guardian Procedure Errors and Messages Manual. attribute-name input STRING .EXT:ref:16 uniquely identifies an attribute.
Guardian Procedure Calls (D-E) DEFINESETATTR Procedure Considerations • • • • To reset an attribute, either the value parameter can be omitted, or value-len can be -1. “Required” attributes cannot be reset. (See the TACL Reference Manual.) If an error occurs, the contents of the working set are not modified. The form of value, with respect to quotes, depends on the attribute. The use of quotes should be avoided. Quotes can be used with the FILEID, MOUNTMSG, and OWNER attributes.
Guardian Procedure Calls (D-E) DEFINESETLIKE Procedure DEFINESETLIKE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary This procedure can be used to initialize the working set with the attributes in an existing DEFINE.
Guardian Procedure Calls (D-E) DEFINESETLIKE Procedure is the 24-byte array that contains the name of the DEFINE for the procedure to use. The name is left-justified and padded on the right with blanks. Trailing blanks are ignored. Considerations The existing attributes in the working set are deleted. They can be saved in the background set by calling DEFINESAVEWORK prior to calling this procedure.
Guardian Procedure Calls (D-E) DEFINEVALIDATEWORK Procedure DEFINEVALIDATEWORK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary This procedure can be used to check the working set for consistency.
Guardian Procedure Calls (D-E) DEFINEVALIDATEWORK Procedure Considerations • • • • • Subsequent calls to DEFINEREADATTR will return info-word.<13> = 1 if the attribute was involved in an inconsistency. If the last call to DEFINEREADATTR showed that info-word.<13> was set and the DEFINE is currently valid, then a call to DEFINEVALIDATEWORK will clear the flag. DEFINEADD invokes this procedure before creating a DEFINE or replacing an existing DEFINE with the working set.
Guardian Procedure Calls (D-E) DELAY Procedure (Superseded by PROCESS_DELAY_ Procedure (H- DELAY Procedure (Superseded by PROCESS_DELAY_ Procedure (H-Series RVUs Only)) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The DELAY procedure permits a process to suspend itself for a timed interval.
DELAY Procedure (Superseded by PROCESS_DELAY_ Procedure (H- Guardian Procedure Calls (D-E) • Measuring time by the processor clock The DELAY procedure measures time according to the internal clock of the processor in which the calling process is executing. Typically, processor time (that is, time as measured by a particular processor) is slightly different from system time; it also varies slightly from processor to processor, because all the processor clocks typically run at slightly different speeds.
DELETEEDIT Procedure Guardian Procedure Calls (D-E) DELETEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (D-E) DELETEEDIT Procedure is the number that identifies the open file from which lines are to be deleted. input first INT(32):value specifies 1000 times the line number of the first line in the range of lines to be deleted. If a negative value is specified, the line number of the first line in the file is used. input last INT(32):value specifies 1000 times the line number of the last line in the range of lines to be deleted.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Device Attributes and Value Representations Example Related Programming Manual Summary Note. On G-series releases, this procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (D-E) • DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) The parameter maxlen specifies the maximum length in bytes of the character string pointed to by devname. The actual length of the name returned in devname is returned in devname-len. All three of these parameters must either be supplied or be absent.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) input ldevnum INT(32):value specifies a logical device number that is used in one of the following ways: • • If options.<15> is equal to 0, ldevnum designates the device for which information is requested. If options.<15> is equal to 1, the procedure begins a search of devices starting with the logical device number immediately following ldevnum. See the options parameter, later in this subsection.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) 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. If this parameter is present, primary-info-maxlen and primary-info-len must also be present.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) backup-info-maxlen input INT:value specifies the length in bytes of the buffer pointed to by backup-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 backup-info is present. backup-info-len output INT .
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) input match-type INT:value if present and if not -1, specifies a device type that is to be used as a search criterion. Supplying match-type causes the procedure to return information for the next device that has a device type of match-type and a logical device number greater than ldevnum. options.<14> and options.<15> must both be equal to 1 in order to use this parameter.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) error-detail output INT .EXT:ref:1 for some returned errors, contains additional information. See error, earlier in this subsection. Considerations • I/O process status The physical information that is returned in primary-info and backup-info includes a status field (see “Device Attributes and Value Representations,” later in this subsection).
DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) Guardian Procedure Calls (D-E) Device Attributes and Value Representations The following set of attributes is returned in logical-info if that parameter is present: Attribute TAL Value Representation ldev INT(32) primary-processor INT primary-PIN INT backup-processor INT backup-PIN INT type INT subtype INT record-size INT audited UNSIGNED(1) dynamically-configured UNSIGNED(1) demountable UNSIGNED(1) has-subnames (12
DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) Guardian Procedure Calls (D-E) • type is the device type of the device. See Appendix A, Device Types and Subtypes for a list of device types. • subtype is the device subtype of the device. See Appendix A, Device Types and Subtypes for a list of device subtypes. • record-size is the record size of the device. • audited if equal to 1, indicates that the device is TMF audited.
DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) Guardian Procedure Calls (D-E) Attribute TAL Value Representation 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 unit INT state INT path 3 information: configured UNSIGNED(1) in-use (14 bits of filler) UNSIGNED(1)
Guardian Procedure Calls (D-E) • DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) mirror-subtype is the device subtype of the mirror disk of a logical volume. This field is set only by the disk process. • 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.
Guardian Procedure Calls (D-E) • DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) state is the current state of the path. If the device has only one path, then the state of the device is the state of the path. Valid state values include: Value Description 0 UP 1 DOWN 2 SPECIAL 3 MOUNT 4 5 REVIVE (reserved) 6 EXERCISE 7 EXCLUSIVE 8 HARD DOWN 9 UNKNOWN Example ! obtain logical and physical attributes for ! logical device 10.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary Note. On G-series releases, 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.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) Syntax for TAL Programmers error := DEVICE_GETINFOBYNAME_ ( devname:length i:i ,[ 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 ] ,[ error-detail ] ); ! ! o ! i ! o ! o ! i ! o ! o ! i ! o ! i ! o Parameters returned value error INT indicates the outcome
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) 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. The attribute values are returned in a contiguous array. If this parameter is present, logical-info-maxlen and logical-info-len must also be present.
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) input primary-info-maxlen 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 .
Guardian Procedure Calls (D-E) DEVICE_GETINFOBYNAME_ Procedure (Superseded on G-Series Releases) input timeout 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. error-detail output INT .EXT:ref:1 for some returned errors, contains additional information. See error, earlier in this subsection.
Guardian Procedure Calls (D-E) DEVICEINFO Procedure (Superseded by FILE_GETINFOBYNAME_ 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.
Guardian Procedure Calls (D-E) DEVICEINFO Procedure (Superseded by FILE_GETINFOBYNAME_ output devtype INT:ref:1 returns the device type of the associated file in this form: <0> <1> <2:3> <4:9> <10:15> Demountable Audited disk, or the file name specified was a subdevice Undefined Device type Device subtype If the device type is greater than 63, bits <4:9> are set to 44.
Guardian Procedure Calls (D-E) DEVICEINFO2 Procedure (Superseded by FILE_GETINFOBYNAME_ 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.
DEVICEINFO2 Procedure (Superseded by FILE_GETINFOBYNAME_ Guardian Procedure Calls (D-E) the remaining 16 characters still must be in a valid file name format. If a logical device number is specified, the last 16 characters must be blanks.
Guardian Procedure Calls (D-E) DEVICEINFO2 Procedure (Superseded by FILE_GETINFOBYNAME_ input options INT:value is a word indicating the options desired: <0:12> should be zero. <13> if 1, indicates that this call is initiating a nowait inquiry and the information will be returned in a system message. Do not set both options.<13> and options.<14> to 1. See “Considerations” for more information.
Guardian Procedure Calls (D-E) • DEVICEINFO2 Procedure (Superseded by FILE_GETINFOBYNAME_ If you call this procedure in a nowait manner (options <13> is set to 1), the results are returned in the nowait DEVICEINFO2 completion message (-41), not in the output parameters of the procedure. The format of this completion message is described in the Guardian Procedure Errors and Messages Manual. If error is not 0, no completion message is sent to $RECEIVE.
Guardian Procedure Calls (D-E) DISK_REFRESH_ Procedure DISK_REFRESH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary Note. On G-series releases, 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.
DISK_REFRESH_ Procedure Guardian Procedure Calls (D-E) Syntax for TAL Programmers error := DISK_REFRESH_ ( name:length ); ! i:i Parameters returned value error INT is a file-system error number indicating the outcome of the operation. input:input name:length 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.
Guardian Procedure Calls (D-E) DISKINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ DISKINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration Example Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. This procedure obtains information about disk volumes.
Guardian Procedure Calls (D-E) DISKINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ input name INT .EXT:ref:12 is the name of the disk volume being inquired about. The name can be that of a disk volume (blank padded), or of a disk file, or of a DEFINE designating a disk volume or file. The name can refer to a disk on a different network node. output capacity INT(32) .EXT:ref:1 is the information capacity of the volume as labeled, in pages (2048 byte units).
Guardian Procedure Calls (D-E) DISKINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ output drivecaps INT(32) .EXT:ref:2 are the formatted capacities of the primary and mirror drives, in pages. These values account for the space taken up for data protection (such as spare sectors), but not for other uses. If the information is unavailable for a drive (because it is inaccessible or not configured), its corresponding value is zero.
DNUMIN Procedure Guardian Procedure Calls (D-E) DNUMIN Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The DNUMIN procedure converts the ASCII characters used to represent a number into the signed double word integer value for that number. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (D-E) DNUMIN Procedure ascii-number input STRING .EXT:ref:* is an array containing the number to be converted to signed double word integer form. ascii-number is of the form: [ + ] [ prefix ] number nonnumeric [ - ] where any of the following prefix values can be used to override the specified base: % octal # decimal %b or %B binary %h or %H hexadecimal The number cannot contain embedded commas. signed-result output INT(32) .
Guardian Procedure Calls (D-E) DNUMIN Procedure <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. Considerations • • • Number conversion stops on the first ASCII character that either does not represent any numeric value or that represents a numeric value greater than (base -1).
DNUMOUT Procedure Guardian Procedure Calls (D-E) DNUMOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (D-E) DNUMOUT Procedure is an array where the converted value is returned in ASCII representation, rightjustified in ascii-result[width - 1], with zero-fill by default. unsigned-doubleword input INT(32):value is the unsigned double-word integer to be converted. input base INT:value is the number base for the resulting conversion. Any number in the range 2 through 36 is valid. input width INT:value is the maximum number of characters permitted in ascii-result.
Guardian Procedure Calls (D-E) DNUMOUT Procedure Related Programming Manual For related programming information about the DNUMOUT utility procedure, refer to the Guardian Programmer’s Guide.
DST_GETINFO_ Procedure Guardian Procedure Calls (D-E) DST_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The DST_GETINFO_ procedure, for G05.00 and later G-series releases, provides the information about the DST entry that is in effect at time keygmt.
Guardian Procedure Calls (D-E) DST_GETINFO_ Procedure output dstentry INT.EXT:ref:* specifies the address of the ZSYS^DDL^DST^ENTRY^DEF structure that will be filled in with the required information. Considerations • • If the keygmt value is less the than the lowgmt value of the first entry in the table with nonzero offset, ZSYS^VAL^DST^RANGE^LOW (error 9) is returned.
Guardian Procedure Calls (D-E) DST_TRANSITION_ADD_ Procedure DST_TRANSITION_ADD_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for dstentry Considerations Example Summary The DST_TRANSITION_ADD_ procedure, for G05.00 and later G-series releases, allows a super-group user (255,n) to add an entry to the daylight-saving-time (DST) transition table.
Guardian Procedure Calls (D-E) DST_TRANSITION_ADD_ Procedure Table 4-2. Error Summary for DST_* Procedures Error Literal Value Description 0 ZSYS^VAL^DST^OK The operation is successful. 1 ZSYS^VAL^DST^SECURITY^ERROR The caller is not a super-group user (255,n). 2 ZSYS^VAL^DST^BAD^VERSION The version number passed in ZSYS^DDL^DST^ENTRY^DEF is not valid. The only valid version is ZSYS^VAL^DST^VERSION^SE P1997. 3 ZSYS^VAL^DST^BAD^PARAMETER One of the specified parameters is not valid.
Guardian Procedure Calls (D-E) DST_TRANSITION_ADD_ Procedure Table 4-2. Error Summary for DST_* Procedures Error Literal Value Description 9 ZSYS^VAL^DST^RANGE^LOW 10 ZSYS^VAL^DST^RANGE^HIGH 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. The specified keygmt value is greater than the highgmt of the last DST interval with nonzero offset.
Guardian Procedure Calls (D-E) DST_TRANSITION_ADD_ Procedure Structure Definition 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) END; Z^LOWGMT; Z^HIGHGMT; Z^OFFSET; Z^VERSION; Z^FILLER; Z^LOWGMT identifies the lower limit of the interval in Greenwich Mean Time (GMT).
Guardian Procedure Calls (D-E) DST_TRANSITION_ADD_ Procedure 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.
Guardian Procedure Calls (D-E) DST_TRANSITION_DELETE_ Procedure DST_TRANSITION_DELETE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The DST_TRANSITION_DELETE_ procedure, for G05.00 and later G-series releases, 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.
Guardian Procedure Calls (D-E) DST_TRANSITION_DELETE_ Procedure Considerations • Only transition entries that already exist can be deleted. If an interval with nonzero offset covers the time at which the delete operation is attempted, ZSYS^VAL^DST^DELETE^NOW^ERROR (error 5) is returned. Example #include zsys_ddl_dst_entry_def dstentry; short error; long long timeStampLow, timeStampHigh; dstentry.z_lowgmt = timeStampLow; dstentry.z_highgmt = timeStampHigh; dstentry.
DST_TRANSITION_MODIFY_ Procedure Guardian Procedure Calls (D-E) DST_TRANSITION_MODIFY_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The DST_TRANSITION_MODIFY_ procedure, for G05.00 and later G-series releases, 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.
Guardian Procedure Calls (D-E) DST_TRANSITION_MODIFY_ Procedure Considerations • • Transitions with nonzero offsets that already exist can be modified if the new values do not overlap other transitions with nonzero offsets that also exist. If you specify an offset value of zero for newdst, the olddst entry is deleted.
EDITREAD Procedure Guardian Procedure Calls (D-E) EDITREAD Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (D-E) EDITREAD Procedure >= 0 Indicates that the reading of the file was successful. This is the actual number of characters in the text line. However, no more than bufferlen bytes are transferred into buffer. <0 Indicates an unrecoverable error, where: -1 End of file encountered -2 Error occurred while reading -3 Text file format error -4 Sequence error. The sequence number of the line just read is less than its predecessor. -5 Checksum error.
Guardian Procedure Calls (D-E) EDITREAD Procedure If reading the file is successful, a count of the number of bytes in the text line returns in COUNT, the text line returns in the array LINE, and the sequence number returns in SEQ^NUM.
Guardian Procedure Calls (D-E) EDITREADINIT Procedure EDITREADINIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (D-E) EDITREADINIT Procedure -3 Format error (not EDIT file), or buffer length is incorrect -6 Invalid buffer address. Edit control block was not within lower half of user data stack. edit-controlblk output INT:ref:* is an uninitialized array that is declared globally. Forty words of the edit control block are used for control information. The remainder is used as an internal buffer by EDITREAD.
Guardian Procedure Calls (D-E) ERRNO_GET_ Procedure ERRNO_GET_ Procedure Summary Considerations for C Programmers Syntax for TAL Programmers Parameters Example Considerations Summary The ERRNO_GET_ procedure obtains the value of the errno variable set by many OSS, native C/C++, and some Guardian routines.
EXTENDEDIT Procedure Guardian Procedure Calls (D-E) EXTENDEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (D-E) EXTENDEDIT Procedure input, output filenum INT .EXT:ref:1 specifies the file number of the open file to be copied into a new file. It returns the file number of the new file. input start 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.
5 Guardian Procedure Calls (F) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter F. Table 5-1 lists all the procedures in this section. Table 5-1.
Guardian Procedure Calls (F) Table 5-1.
Guardian Procedure Calls (F) FILE_ALTERLIST_ Procedure FILE_ALTERLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_ALTERLIST_ Procedure STRING .EXT:ref:*, INT:value specifies the name of the file to be altered. The value of filename must be exactly length bytes long. It must be a valid disk file name. If the name is partially qualified, it is resolved using the contents of the VOLUME attribute of the =_DEFAULTS DEFINE. input item-list INT .EXT:ref:* is an array that specifies the file attributes for which new values are supplied in the values parameter.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) output error-item INT .EXT:ref:1 if present, returns the index of the item in item-list that was being processed when an error was detected, or is one greater than the number of items if an error was detected after the processing of individual items was completed. The index of the first item in item-list is 0. Considerations • • • • • The specified file cannot be open when FILE_ALTERLIST_ is called.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 2 of 9) 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. Code Size (bytes) 70 2 Refresh EOF. For disk objects other than SQL shorthand views, a value of 1 if a change to the end-of-file value is to cause the file label to be written immediately to disk; 0 otherwise.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 3 of 9) 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. Code Size (bytes) 93 * Partition-volume names. A string containing the concatenated names of all the secondary partition volumes, ordered by partition number.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 4 of 9) 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. Code Size (bytes) 99 * Description Partition-volume relative names. Concatenated names of the extra partition volumes.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 5 of 9) 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. Code Size (bytes) Description key-len (INT:1) specifies the length, in bytes, of the alternate-key field.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 6 of 9) 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. Code Size (bytes) Description <0> = 1 means a null value is specified. <1> = 1 means the key is unique.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 7 of 9) 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. Code Size (bytes) 104 * Description Alternate-file names. A string array containing the concatenated names of the alternate-key files.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 8 of 9) 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. Code Size (bytes) 106 * Description Alternate-key descriptors (32-bit). An array of 14-byte key descriptor entries, one for each alternate key.
FILE_ALTERLIST_ Procedure Guardian Procedure Calls (F) Table 5-2. FILE_ALTERLIST_ Item Codes (page 9 of 9) 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. Code Size (bytes) 109 * Description Alternate-file relative names. Concatenated names of the alternate-key files.
Guardian Procedure Calls (F) FILE_CLOSE_ Procedure FILE_CLOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_CLOSE_ Procedure is one of the following values, indicating the tape control action to take: 0 1 2 3 4 5 Rewind and unload; do not wait for completion. Rewind and unload, do not wait for completion. Rewind and leave online; do not wait for completion. Rewind and leave online; wait for completion. Do not rewind; leave online. Reserved for parallel backup. Other input values result in no error if the file is a tape device; the control action might be unpredictable.
Guardian Procedure Calls (F) FILE_CLOSE_ Procedure Related Programming Manuals For programming information about the FILE_CLOSE_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILE_CLOSE_CHKPT_ Procedure FILE_CLOSE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) 1 2 3 4 FILE_CLOSE_CHKPT_ Procedure Rewind and take offline; do not wait for completion Rewind and leave online; do not wait for completion Rewind and leave online; wait for completion Do not rewind; leave online Other input values result in an error if the file is a tape device; otherwise they are ignored. If omitted, 0 is used.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure FILE_COMPLETE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for completion-info General Considerations Considerations for Guardian Files Considerations for OSS Files Related Programming Manuals Summary The FILE_COMPLETE_ procedure completes one previously initiated I/O operation for a Guardian file or returns ready information for one Open System Services (OSS) file.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure Syntax for TAL Programmers status := FILE_COMPLETE_ ( completion-info ,[ timelimit ] ,[ complete-element-list ] ,[ num-complete-elements ] ,[ error-complete-element ] ); ! ! ! ! ! o i i i o Parameters returned value status INT is a file-system error number indicating the outcome of the call to the FILE_COMPLETE_ procedure. Error 26 is returned if a timelimit value of -1D (indefinite wait) is specified but no I/O operation has been initiated.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure < -1D An invalid value (file-system error 590 occurs). omitted Wait indefinitely. complete-element-list input INT .EXT:ref:*(ZSYS^DDL^COMPLETE^ELEMENT^DEF) is an array of COMPLETE^ELEMENT structures, each structure describing one Guardian file or OSS file. The array explicitly specifies the set of files from which the caller wants the FILE_COMPLETE_ procedure to complete one file.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure Structure Definition 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 structure for the completion-info parameter is defined in the ZSYS* files.
Guardian Procedure Calls (F) 0 1 FILE_COMPLETE_ Procedure The file is a Guardian file. The file is an OSS file. Z^ERROR returns a file-system error number for the completion on this file. Z^FNUM^FD returns the Guardian file number or OSS file descriptor of the file completed by this call. Z^COMPLETION^TYPE returns the type of operation completed on an OSS file. More than one state can be ready. (For Guardian files, this space is replaced by Z^COUNT^TRANSFERRED.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure General Considerations • • Completion on a file by a call to the FILE_COMPLETE_ procedure does not remove it from the set of enabled files. Each file that is enabled for completion is enabled for multiple completions until your program removes it from the enabled set or closes it.
Guardian Procedure Calls (F) FILE_COMPLETE_ Procedure file will finish successfully, For 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_ procedure returns ready information for only one file at a time.
Guardian Procedure Calls (F) FILE_COMPLETE_GETINFO_ Procedure FILE_COMPLETE_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_COMPLETE_GETINFO_ Procedure or FILE_COMPLETE_ SET_ procedure. For the definitions of the fields of the COMPLETE^ELEMENT structure, see Structure Definition for COMPLETE^ELEMENT on page 5-29. maxnum-info-elements input INT specifies the maximum number of COMPLETE^ELEMENT structures that can be returned in the info-list parameter. num-info-elements output INT .EXT returns the number of COMPLETE^ELEMENT structures that are returned in the info-list parameter.
Guardian Procedure Calls (F) FILE_COMPLETE_SET_ Procedure FILE_COMPLETE_SET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for COMPLETE^ELEMENT General Considerations Considerations for Guardian Files Considerations for OSS Files 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.
Guardian Procedure Calls (F) FILE_COMPLETE_SET_ Procedure Syntax for TAL Programmers status := FILE_COMPLETE_SET_ ( complete-element-list ,num-complete-elements ,[ error-complete-element ] ); ! i ! i ! o Parameters returned value status INT is a file-system error number indicating the outcome of the operation. complete-element-list input INT .EXT:ref:*(ZSYS^DDL^COMPLETE^ELEMENT^DEF) is an array of COMPLETE^ELEMENT structures.
Guardian Procedure Calls (F) FILE_COMPLETE_SET_ Procedure The COMPLETE^ELEMENT structure is defined in the ZSYS* files.
Guardian Procedure Calls (F) FILE_COMPLETE_SET_ Procedure Z^OPTIONS specifies attributes for the OSS file or Guardian file. It contains the following fields: Z^SET^FILE can have these values: 0 1 Add this file to the set of files that are enabled for completion. Remove this file from the set of files that are enabled for completion. Z^FILETYPE can have these values: 0 1 This file is a Guardian file. This file is an OSS file.
Guardian Procedure Calls (F) FILE_COMPLETE_SET_ Procedure General 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.
Guardian Procedure Calls (F) FILE_CREATE_ Procedure FILE_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_CREATE_ Procedure 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 returned value error INT is a file-system error number indicating the outcome of the operation.
Guardian Procedure Calls (F) FILE_CREATE_ Procedure primary-extent-size input INT:value specifies the size of the primary extent in pages (2048-byte units). The value is considered to be unsigned. The system might round the value up to an even number during file creation. The maximum primary extent size is 65,535 (134,215,680 bytes). If this parameter is omitted or equal to 0, 1 is used. secondary-extent-size input INT:value specifies the size of the secondary extents in pages (2048-bytes units).
Guardian Procedure Calls (F) FILE_CREATE_ Procedure input options INT:value specifies optional file attributes. If omitted, the default value of options is 0. The bits, when set, indicate the following: <0:8> Reserved (must be 0). <9> Queue file. The file will be a queue file. <10> Refresh EOF. A change to the end-of-file value is to cause the file label to be written immediately to disk. <11> Index compression. For key-sequenced files, the entries in the index blocks are to be compressed.
Guardian Procedure Calls (F) FILE_CREATE_ Procedure input blocklen INT:value for structured files, specifies the length in bytes of each block of records in the file. For unstructured files, it controls the buffer size used internally but does not limit user transfer sizes (though data transfers are more efficient when they do not exceed blocklen). For structured files, blocklen must be at least recordlen + 24. For keysequenced files, blocklen must be at least recordlen + 34.
Guardian Procedure Calls (F) • FILE_CREATE_ Procedure Odd unstructured files An odd unstructured file permits reading and writing of odd byte counts and positioning to odd byte addresses. If options.<15> is 1 and file-type is 0, 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 file-type is 0 and options.
Guardian Procedure Calls (F) FILE_CREATE_ Procedure When creating a file on a SMF virtual volume, the system chooses the physical volume on which the file will reside. If you want to specify the physical volume, you must create the file using the FILE_CREATELIST_ procedure. Safeguard Considerations For information on files protected by Safeguard, refer to the Safeguard Reference Manual. OSS Considerations • • This procedure operates only on Guardian objects.
Guardian Procedure Calls (F) FILE_CREATELIST_ Procedure FILE_CREATELIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_CREATELIST_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. 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, it is the name of the disk volume on which the file is to be created.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) variable-length item has an associated value that gives its length, as specified in the table. input values-length INT:value is the size in bytes of values. output error-item INT .EXT:ref:1 if present, returns the index of the item in item-list that was being processed when an error was detected, or is one greater than the number of items in item-list if an error was detected after the processing of individual items was completed.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 2 of 12) 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. Item Code Size (Bytes) 44 2 Block length. For structured disk objects, the size of a block of records; for unstructured disk files, controls the internal buffer size.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 3 of 12) 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. Item Code Size (Bytes) 57 8 Expiration time. For disk objects other than SQL shorthand views, the Julian GMT timestamp giving the time before which the file cannot be purged. 65 2 Odd unstructured.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 4 of 12) 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. Item Code Size (Bytes) 72 2 Description Write through. For disk objects, a value of 1 specifies writethrough caching; a value of 0 specifies that writes to the file are to be buffered.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 5 of 12) 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. Item Code Size (Bytes) 92 * Partition-volume name-length array.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 6 of 12) 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. Item Code Size (Bytes) 98 * Partition-volume relative names-length array.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 7 of 12) 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. Item Code Size (Bytes) 101 (continued) Description key-len (INT:1) specifies the length in bytes of the alternatekey field.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 8 of 12) 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. Item Code Size (Bytes) 101 (continued) Description <0> = 1 means a null value is specified. <1> = 1 means the key is unique.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 9 of 12) 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. Item Code Size (Bytes) 104 * Alternate-file names. For disk files, a string array containing the concatenated names of the alternate-key files.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 10 of 12) 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. Item Code Size (Bytes) 109 * Description Alternate-file relative names. Concatenated names of the alternate-key files.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 11 of 12) 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. Item Code Size (Bytes) Description The items 187 and188 are optional when creating a partitioned SMF file.
FILE_CREATELIST_ Procedure Guardian Procedure Calls (F) Table 5-3. FILE_CREATELIST_ Item Codes (page 12 of 12) 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. Item Code Size (Bytes) 198 4 Key offset (32-bit). For key-sequenced disk files, the byte offset from the beginning of the record to the primary key field.
Guardian Procedure Calls (F) FILE_CREATELIST_ Procedure Considerations • Using item-list In general, if you supply an item in item-list that is not applicable (for example, if you supply a logical record length for an unstructured file), FILE_CREATELIST_ ignores the item as long as it passes syntax and value range checks. Exceptions to this are noted in Table 5-3. • File pointer action The end-of-file pointer is set to 0 after the file is created.
Guardian Procedure Calls (F) FILE_CREATELIST_ Procedure extent sizes (items 50, 51, and 91 in item-list) and maximum extents (item 52) yield a file size greater than (2**32) - 4096 bytes (approximately four gigabytes) or a partition size greater than 2**31 bytes (two gigabytes). • Insertion-ordered alternate keys All the nonunique alternate keys of a file must have the same duplicate-keyordering attribute.
Guardian Procedure Calls (F) FILE_CREATELIST_ Procedure Related Programming Manuals For programming information about the FILE_CREATELIST_ procedure, refer to the Enscribe Programmer’s Guide and the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILE_GETINFO_ Procedure FILE_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_GETINFO_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the call to FILE_GETINFO_. input filenum 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” below.
FILE_GETINFO_ Procedure Guardian Procedure Calls (F) [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. For disk files, indicates the file type: 0 1 2 3 -1 [4] unstructured relative entry-sequenced key-sequenced is returned for nondisk files. File code. For disk files, gives the application-defined file code (file codes 100-999 are reserved for use by HP). -1 is returned for nondisk files.
Guardian Procedure Calls (F) FILE_GETINFO_ Procedure Example error := FILE_GETINFO_ ( filenum, lasterror ); ! ! ! ! obtain error from last file operation Related Programming Manuals For programming information about the FILE_GETINFO_ procedure, refer to the Guardian Programmer’s Guide. For information about SQL objects, refer to the Introduction to NonStop SQL/MP and the appropriate HP NonStop SQL/MP or HP NonStop SQL/MX programming manual.
Guardian Procedure Calls (F) FILE_GETINFOBYNAME_ Procedure FILE_GETINFOBYNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
FILE_GETINFOBYNAME_ Procedure Guardian Procedure Calls (F) Parameters returned value error INT is a file-system error number indicating the outcome of the operation. input:input filename:length STRING .EXT:ref:*, INT:value specifies the 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. output type-info INT .
Guardian Procedure Calls (F) disk files FILE_GETINFOBYNAME_ Procedure physical-recordlen is the maximum possible transfer length. Transfer length is equal to the configured buffer size for the device (either 2048 or 4096 bytes). (For an Enscribe disk file, the logical record length can be obtained by a call to FILE_GETINFOLIST[BYNAME]_.) processes and $RECEIVE file A length of 132 is returned in physical-recordlen. This is the system convention for interprocess files.
Guardian Procedure Calls (F) <0:14> Reserved and undefined. <15> File is an OSS file. FILE_GETINFOBYNAME_ Procedure Considerations • Specifying a subtype 30 process When FILE_GETINFOBYNAME_ is called with a file name that designates a subtype 30 process, the procedure sends a device type inquiry system message to the process to determine the device type and subtype (unless disabled by options.<15>).
Guardian Procedure Calls (F) FILE_GETINFOBYNAME_ Procedure OSS Considerations • • Use the flags parameter of FILE_GETINFO_ or FILE_GETINFOBYNAME_ or use item code 161 of FILE_GETINFOLIST_ or FILE_GETINFOLISTBYNAME_ to determine whether the file is an OSS file. Use the item-list parameter of FILE_GETINFOLIST_ or FILE_GETINFOLISTBYNAME_ to specify which OSS file attribute values are to be returned.
Guardian Procedure Calls (F) FILE_GETINFOLIST_ Procedure FILE_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFOLIST_ procedure obtains detailed information about a file identified by file number. A related (and simpler to use) procedure, FILE_GETINFO_, obtains a limited set of information about a file identified by file number.
Guardian Procedure Calls (F) FILE_GETINFOLIST_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. input filenum 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.
Guardian Procedure Calls (F) FILE_GETINFOLIST_ Procedure result-length output INT .EXT:ref:1 returns the length in bytes of the array of values returned in result. resultlength is an odd value only if the last value in the array has an odd length. output error-item INT .EXT:ref:1 returns the index of the item that was being processed when an error was detected. The index of the first item in item-list is 0.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) • • • • The FILE_GETINFOLIST_ procedure should not be used to determine, the current-key-value parameter for queue files (item code 15), because a current key position is not maintained for queue files. Support for SQL files includes both Format 1 and Format 2 files. If the file being referenced is a Format 2 file and the extent size exceeds 65535, item codes will return -1 with no error indication.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 2 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 8 2 Last-error detail.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 3 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 17 * Current primary-key value.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 4 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 31 2 Device subtype.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 5 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 44 2 Block length.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 6 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 57 8 Expiration time.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 7 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 67 2 Audit compression.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 8 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 78 2 Broken.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 9 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 92 * Partition-volume name-length array.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 10 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 99 * Partition-volume relative names.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 11 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 106 * Description Alternate-key descriptors (32-bit).
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 12 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 112 4 Volume fragments.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 13 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 118 8 Expiration LCT.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 14 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 142 4 Aggregate EOF.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 15 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 165 4 166 2 167 4 File owner.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 16 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 180 2 Physical volume primary processor.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 17 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 197 4 Block length (32-bit).
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 18 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object. Item Code Size (Bytes) 212 2 Block checksumming option.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 19 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 20 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object.
FILE_GETINFOLIST_ Procedure Guardian Procedure Calls (F) Table 5-4. FILE_GETINFOLIST_ Item Codes (page 21 of 21) 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. Items described as “Applies only to SQL/MX objects” return file system error 2 if queried on anything that is not an SQL/MX object.
Guardian Procedure Calls (F) FILE_GETINFOLIST_ Procedure OSS Considerations • The following item codes are not applicable to OSS objects but do not cause an error to be returned: 50, 51, 59, 60, 61, and 62.
Guardian Procedure Calls (F) FILE_GETINFOLISTBYNAME_ Procedure FILE_GETINFOLISTBYNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_GETINFOLISTBYNAME_ procedure obtains detailed information about a file identified by file name. A related (and simpler to use) procedure, FILE_GETINFOBYNAME_, obtains a limited set of information about a file identified by file name.
Guardian Procedure Calls (F) FILE_GETINFOLISTBYNAME_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. 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. input item-list INT .
Guardian Procedure Calls (F) FILE_GETINFOLISTBYNAME_ Procedure result-length output INT .EXT:ref:1 returns the length in bytes of the array of values returned in result. resultlength is an odd value only if the last value in the array has an odd length. output error-item INT .EXT:ref:1 returns the index of the item that was being processed when an error was detected. The index of the first item in item-list is 0.
Guardian Procedure Calls (F) FILE_GETINFOLISTBYNAME_ Procedure The subtype 30 process replies with the requested information in system message -40 or -106, corresponding to the original message. The returned device type value should be one of those listed in Appendix A, Device Types and Subtypes. If the message response is incorrectly formatted, the FILE_GETINFOLISTBYNAME_ caller receives device type and subtype values of 0. The REPLY caller (the subtype 30 process) receives an error 2.
Guardian Procedure Calls (F) FILE_GETINFOLISTBYNAME_ Procedure number^of^items, result, result^max ); Related Programming Manuals For programming information about the FILE_GETINFOLISTBYNAME_ procedure, refer to the Guardian Programmer’s Guide. For information about SQL objects, refer to the Introduction to NonStop SQL/MP and the appropriate SQL/MP or SQL/MX programming manual.
Guardian Procedure Calls (F) FILE_GETLOCKINFO_ Procedure FILE_GETLOCKINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_GETLOCKINFO_ Procedure Syntax for TAL Programmers error := FILE_GETLOCKINFO_ ( name:length ,[ processhandle ] ,[ transid ] ,control ,lock-descr ,lock-descr-length ,participants ,max-participants ,[ locked-name:maxlen ] ,[ locked-name-length ] ); ! ! ! ! ! ! ! ! ! ! i:i i i i,o o i o i o:i o Parameters returned value error INT is a file-system error number indicating the outcome of the operation.
Guardian Procedure Calls (F) FILE_GETLOCKINFO_ Procedure input:input name:length 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.
FILE_GETLOCKINFO_ Procedure Guardian Procedure Calls (F) The information is returned in the following format: [0] Lock type. 0 indicates a file lock; 1 indicates a record lock. [1] Flags. The bits are: <0> = 1 Indicates a generic lock <1:15> (reserved) [2] The number of participants (the number of holders and waiters for the lock). [3:4] Record specifier (4 bytes) if the lock is a record lock on a Format 1 file that is not key-sequenced; undefined otherwise.
Guardian Procedure Calls (F) [2:5] FILE_GETLOCKINFO_ Procedure The transid of the participant (if participants[0].<0> = 0). input max-participants 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 .EXT:ref:*, INT:value if present and a volume name is supplied for name, returns the subvolume and file identifier (the two rightmost parts of the file name) of the file on which the lock is set.
Guardian Procedure Calls (F) FILE_GETLOCKINFO_ Procedure Example ! The following code obtains all the available information ! about locks on the specified disk file and about all the ! holders/waiters.
Guardian Procedure Calls (F) FILE_GETOPENINFO_ Procedure FILE_GETOPENINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_GETOPENINFO_ Procedure Syntax for TAL Programmers error := FILE_GETOPENINFO_ ( searchname:length ,prevtag ,[ primary-opener ] ,[ backup-opener ] ,[ accessmode ] ,[ exclusion ] ,[ syncdepth ] ,[ filename:maxlen ] ,[ filenamelen ] ,[ accessid ] ,[ validmask ] ); ! ! ! ! ! ! ! ! ! ! ! i:i i,o o o o o o o:i o o o Parameters returned value error INT is a file-system error number indicating the outcome of the operation. Error 1 (EOF) indicates that there are no more opens.
Guardian Procedure Calls (F) FILE_GETOPENINFO_ Procedure backup-opener output INT .EXT:ref:10 is the process handle of the backup opener process associated with the primary open. A null process handle (-1 in each word) is returned if there is no backup opener. output accessmode INT .EXT:ref:1 is the access mode with which the file is open. The values are: 0 1 2 read-write read only write only output exclusion INT .EXT:ref:1 is the exclusion mode with which the file is open.
Guardian Procedure Calls (F) FILE_GETOPENINFO_ Procedure output validmask INT .EXT:ref:1 returns a value indicating which of the output parameters has returned valid information. Each parameter has a corresponding bit that is set to 1 if the parameter is valid for the device, as follows: <0> <1> <2> <3> <4> <5> <6> primary-opener backup-opener accessmode exclusion syncdepth filename accessid Considerations • • Opens are not returned in any defined order.
Guardian Procedure Calls (F) FILE_GETRECEIVEINFO_ Procedure FILE_GETRECEIVEINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The FILE_GETRECEIVEINFO_ procedure returns information about the last message read on the $RECEIVE file. Because this information is contained in the file’s mainmemory resident access control block (ACB), the application process is not suspended by a call to FILE_GETRECEIVEINFO_.
Guardian Procedure Calls (F) FILE_GETRECEIVEINFO_ Procedure receive-info output INT .EXT:ref:17 is a block of words describing the last message read on the $RECEIVE file. It has the following 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. The maximum number of bytes of data that can be returned b\y REPLY.
FILE_GETRECEIVEINFO_ Procedure Guardian Procedure Calls (F) output dialog-info INT .EXT:ref:1 is used by context-sensitive Pathway servers. The dialog-info parameter returns dialog information about the server-class send operation that was initiated by a requester with a Pathsend procedure call. The bits of dialog-info have the following meanings: [0:11] Reserved [12:13] Dialog status. Indicates the last operation performed by the message sender.
Guardian Procedure Calls (F) FILE_GETRECEIVEINFO_ Procedure to sending the message. (Therefore, a process’s first sync ID subsequent to an open has a value of 0.) • Duplicate requests The sync ID allows the server process (that is, the process reading $RECEIVE) to detect duplicate requests from requester processes. Such duplicate requests are caused by a backup requester process reexecuting the latest request of a failed primary requester process, or by certain network failures. Note.
FILE_GETSYNCINFO_ Procedure Guardian Procedure Calls (F) FILE_GETSYNCINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_GETSYNCINFO_ Procedure Parameters error INT:value is a file-system error code that gives the status of the operation. input filenum INT:value is the number that identifies the open file. output infobuf INT:EXT.ref:* is where the synchronization information is stored. The size is given in the infomax parameter. input infomax INT:value specifies the size in bytes of the infobuf parameter. See “Considerations.” output infosize INT:EXT.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure FILE_OPEN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Disk File Considerations Consideration for Terminals Interprocess Communication Considerations System Message DEFINE Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary The FILE_OPEN_ procedure establishes a communication path between an application process and a file.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure 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 returned value error INT is a file-system error number indicating the outcome of the operation.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure input, output filenum INT .EXT:ref:1 returns a number that is used to identify the file in subsequent file-system calls. If the file cannot be opened, a value of -1 is returned. filenum is used as an input parameter only when you are attempting a backup open. In that case, you must supply the primary-processhandle parameter or else the input value of filenum is ignored.
FILE_OPEN_ Procedure Guardian Procedure Calls (F) 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.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure input options INT:value specifies optional characteristics. The bits, when set to 1, indicate the following: <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. (For unstructured files, setting this bit to 1 causes secondary partitions to be inaccessible.) Must be 0 for other devices. <1> Nowait open processing.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure that the meaning of this flag is opposite from that of the equivalent flag in the OPEN procedure). For other device types, this bit must be 0. options (continued) When options is omitted, 0 is used. seq-block-buffer-id input INT:value if present and not 0, identifies the buffer to be used for shared sequential block buffering; all opens made through FILE_OPEN_ and using this ID share the same buffer. Any integer value can be supplied for this parameter.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure input elections INT (32) :value, input specifies the following options: <0:30> <31> Reserved (specify 0). Use 64-bit primary keys. For disk files only, bit <31> specifies that 64bit primary-key values are used instead of 32-bit values for unstructured, relative, or entry-sequenced files. Bit <31> is ignored for key-sequenced files and nondisk devices. The elections parameter can be used with both Format 1 and Format 2 files. If omitted, 0 is used.
FILE_OPEN_ Procedure Guardian Procedure Calls (F) Multiple opens on a given file can create a deadlock. The following shows how a deadlock situation occurs: error := FILE_OPEN_ ( myfile:len , filenuma ... ); ! first open on file myfile. . . error := FILE_OPEN_ ( myfile:len , filenumb ... ); ! second open on file myfile. . . error := FILE_OPEN_ ( myfile:len , filenumc ... ); ! third open on file myfile. . ---d . e LOCKFILE ( filenumb, ... ); ! the file is locked a . ! using the file number d .
Guardian Procedure Calls (F) FILE_OPEN_ Procedure 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]. Nowait IO operations on different file numbers (even if for the same file) are independent and may arrive in any order at the destination and may be completed by AWAITIO[X] in any order. • Nowait opens If you open a file in a nowait manner (options.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure A named process can be represented with or without a sequence number. FILE_OPEN_ treats the two name forms differently. • • • If you supply a process file name that includes a sequence number, the process must have a matching sequence number or the open fails with error 14.
FILE_OPEN_ Procedure Guardian Procedure Calls (F) Table 5-5.
Guardian Procedure Calls (F) • FILE_OPEN_ Procedure 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. If the attempted open is in conflict with other opens, the open fails with error 12. Table 5-7 lists the possible current modes and requested modes, indicating whether an open succeeds or fails.
FILE_OPEN_ Procedure Guardian Procedure Calls (F) Table 5-7.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure 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 1. Attempting to open a disk file and specify a nowait-depth value greater than 1 causes FILE_OPEN_ to fail with an error 28.
Guardian Procedure Calls (F) • FILE_OPEN_ Procedure Current-state indicators after an open After successful completion of an open, the current-state indicators have these values: • • • The current position is that of the first record in the file by primary key. The positioning mode is approximate. The comparison length is 0. If READ is called immediately after FILE_OPEN_ for a structured file, it reads the first record in the file; in a key-sequenced file, this is the first record by primary key.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure When process A attempts to open process B, FILE_OPEN_ completes as follows: • • If process B has already opened $RECEIVE with file-management system messages disabled, the open call by process A completes immediately.
Guardian Procedure Calls (F) FILE_OPEN_ Procedure process attempts to open a low-PIN process that does not have this attribute set, the high-PIN process receives file-system error 560. System Message 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).
Guardian Procedure Calls (F) FILE_OPEN_ Procedure The open in this example has the following defaults; waited I/O, exclusion mode (shared), access mode (read/write), sync depth (0). Related Programming Manuals For programming information about the FILE_OPEN_ procedure, refer to the Guardian Programmer’s Guide and the Enscribe Programmer’s Guide.
Guardian Procedure Calls (F) FILE_OPEN_CHKPT_ Procedure FILE_OPEN_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The FILE_OPEN_CHKPT_ procedure is called by a primary process to open a designated file for its backup process. The following two conditions must be met before FILE_OPEN_CHKPT_ can be called successfully: • • The primary process must open the file.
Guardian Procedure Calls (F) FILE_OPEN_CHKPT_ Procedure output status INT .EXT:ref returns a value indicating the cause of the file-system error returned in error.
Guardian Procedure Calls (F) FILE_PURGE_ Procedure FILE_PURGE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_PURGE_ Procedure 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.
Guardian Procedure Calls (F) FILE_PURGE_ Procedure Related Programming Manuals For programming information about the FILE_PURGE_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILE_RENAME_ Procedure FILE_RENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILE_RENAME_ Procedure newname:length input:input STRING .EXT:ref:*, INT:value contains the file name to be assigned to the specified disk file. The value of newname must be exactly length bytes long. It must be a valid disk file name or the name of a DEFINE that designates a valid disk file name. If the file name is partially qualified, it is resolved using the contents of the =_DEFAULTS DEFINE.
Guardian Procedure Calls (F) FILE_RENAME_ Procedure OSS Considerations Error 564 (operation not supported on this file type) is returned if you attempt to rename an OSS file using the FILE_RENAME_ procedure. Example error := FILE_RENAME_ ( filenum, name:name^length ); Related Programming Manuals For programming information about the FILE_RENAME_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILE_RESTOREPOSITION_ Procedure FILE_RESTOREPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary The FILE_RESTOREPOSITION_ procedure supersedes the REPOSITION Procedure (Superseded by FILE_RESTOREPOSITION_ Procedure) 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).
Guardian Procedure Calls (F) FILE_RESTOREPOSITION_ Procedure input savearea INT:EXT.ref:* is the positioning information from the FILE_SAVEPOSITION_ procedure. The size is given by the savemax parameter. input savesize INT:value is the size in bytes of the information in the savearea parameter.
Guardian Procedure Calls (F) FILE_SAVEPOSITION_ Procedure FILE_SAVEPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The FILE_SAVEPOSITION_ procedure supersedes the SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure), and is used to save a disk file’s current file positioning information in anticipation of a need to return to that position.
Guardian Procedure Calls (F) FILE_SAVEPOSITION_ Procedure output savearea INT:EXT.ref:* is the location where the positioning information is received. The size is given by the savemax parameter. input savemax INT:value specifies the savemax parameter size in bytes. output savesize INT:ref.EXT:1 returns the size in bytes of the information in the savearea parameter.
FILE_SETKEY_ Procedure Guardian Procedure Calls (F) FILE_SETKEY_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The FILE_SETKEY_ procedure supersedes the KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure). The FILE_SETKEY_ procedure is used to position by primary or alternate key within a structured file.
FILE_SETKEY_ Procedure Guardian Procedure Calls (F) Parameters error INT:value is a file-system error code that gives the status of the operation. input filenum INT:value is the number that identifies an open-structured disk 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.
Guardian Procedure Calls (F) FILE_SETKEY_ Procedure indicates a non-unique alternate key, the record is skipped only if both its alternate key and its primary key match the corresponding portions of the specified key-value (which should be an alternate key value concatenated with a primary key value) for key-length bytes (which should be the sum of the alternate and primary key lengths). This option is not supported for positioning by primary key in relative or entry-sequenced files.
FILE_SETPOSITION_ Procedure Guardian Procedure Calls (F) FILE_SETPOSITION_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary The FILE_SETPOSITION_ procedure supersedes the POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure). This procedure has the same function as the POSITION procedure but the FILE_SETPOSITION_ procedure accepts an 8-byte record specifier, enabling use with Format 2 files as well as with other files.
FILE_SETPOSITION_ Procedure Guardian Procedure Calls (F) Parameters error INT:value is a file-system error code that gives the status of the operation. input filenum INT:value is the number that identifies the opened file. input recordspecifier INT(64):value is the 8-byte value that specifies the new setting for the current-record and nextrecord pointers. Relative Files The recordspecifier parameter is an 8-byte recordnum value.
FILE_SETSYNCINFO_ Procedure Guardian Procedure Calls (F) FILE_SETSYNCINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Summary The FILE_SETSYNCINFO_ procedure supersedes the SETSYNCINFO Procedure (Superseded by FILE_SETSYNCINFO_ Procedure). Unlike the SETSYNCINFO procedure, the FILE_SETSYNCINFO_ procedure can be used with Format 2 files as well as with other files.
Guardian Procedure Calls (F) FILE_SETSYNCINFO_ Procedure Parameters error INT:value is a file-system error code that gives the status of the operation. input filenum INT:value is the number that identifies the open file. input infobuf INT.EXT:ref:* is the synchronization information returned by the FILE_GETSYNCINFO_ procedure. input infosize INT:value is the size in bytes of the infobuf parameter.
FILEERROR Procedure Guardian Procedure Calls (F) FILEERROR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The FILEERROR procedure is used to determine whether an I/O operation that completed with an error should be retried.
Guardian Procedure Calls (F) • • FILEERROR Procedure 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. • • If the error is an ownership error (error 200) or a path down error (error 201) and the alternate path is operable, FILEERROR returns a 1, indicating that the operation should be retried. If the alternate path is inoperable, a 0 is returned.
Guardian Procedure Calls (F) FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) 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.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Guardian Procedure Calls (F) Syntax for TAL Programmers CALL FILEINFO ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ filenum ] error ] file-name ] ldevnum ] devtype ] extent-size ] eof-pointer ] next-record-pointer ] last-modtime ] filecode ] secondary-extent-size ] current-record-pointer ] open-flags ] subdevice ] owner ] security ] num-extents-allocated ] max-file-size ] partition-size ] num-partitions ] fil
Guardian Procedure Calls (F) FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) input, output file-name INT:ref:12 specifies or returns the internal-format file name of this file. Either filenum or file-name must be passed. If both are passed, file-name returns with the name of the file associated with filenum; if file-name is passed without filenum, error 2 is returned for nondisk files.
Guardian Procedure Calls (F) FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) output devtype INT:ref:1 returns the device type and subtype of the device associated with this primary partition file. If devtype.<0> = 1, this device is a demountable disk volume. See Appendix A, Device Types and Subtypes for a list of device types and subtypes. output extent-size INT:ref:1 for disk files, returns the primary extent size in 2048-byte units.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Guardian Procedure Calls (F) output filecode INT:ref:1 for disk files only, returns the application-defined file code that is assigned when the file is created. output secondary-extent-size INT:ref:1 for disk files only, returns the size of the secondary file extents in 2048-byte units. A returned value of -1 in this parameter means that the extent size cannot fit into this unsigned 2-byte parameter.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Guardian Procedure Calls (F) <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. <10:11> Is the exclusion mode: Shared access Exclusive access Protected access 0 1 3 <12:15> Is the maximum number of concurrent nowait I/O operations that can be in progress on this file at any given time. open-flags.<12:15> = 0 implies wait I/O.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Guardian Procedure Calls (F) [1] Returns the reading security of the file. [2] Returns the writing security of the file. [3] Returns the execution security of the file. [4] Returns the purging security of the file.
FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Guardian Procedure Calls (F) Specifies object type for SQL object file: <5:7> 0 2 4 5 7 <9> 1 File is not SQL File is an SQL table File is an SQL index File is an SQL protection view File is an SQL shorthand view For interrogating queue files. <10> 1 Indicates REFRESH is specified for this file. <11> 1 For key-sequenced files, indicates index compression is specified.
Guardian Procedure Calls (F) FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) <4> 0 1 Crash-open flag off Crash-open flag on (This is meaningful with the file-name parameter only.) <5> 0 1 Rollforward needed flag off Rollforward needed flag on <6> 0 1 Broken file flag off Broken file flag on <7> 0 1 File closed File is either open or has an incomplete TMF transaction against it. (This is meaningful with the file-name parameter only.
Guardian Procedure Calls (F) FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Table 5-8.
Guardian Procedure Calls (F) • FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Error returned when a file number is specified If FILEINFO is called specifying filenum, the last error associated with this file number is returned. If the file is opened more than once, only errors associated with filenum are returned; errors for the other opens are ignored. Note that the error returned might not originate from the last operation on the file.
Guardian Procedure Calls (F) • FILEINFO Procedure (Superseded by FILE_GETINFOLIST_ Procedure ) Referencing Format 2 files with extent size greater than 65535 If the file being referenced is a Format 2 file and the extent size exceeds 65535, item codes will return -1 with no error indication. Examples CALL FILEINFO ( FILENUM , ERROR ); ! get error of read ! operation.
Guardian Procedure Calls (F) FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ 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 FILEINQUIRE procedure is used to obtain items of information about a file.
Guardian Procedure Calls (F) FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) input file-name INT:ref:12 is an internal-format file name that identifies the file being inquired about. Required if filenumber is not specified. May not be specified if filenumber is specified. A define-name can be given for this parameter. input item-list INT:ref:* is an array in which the caller specifies the items of file information to be returned by the procedure.
FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) Condition Code Settings < (CCL) indicates that an error occurred (see error-code). = (CCE) indicates that the FILEINQURE was successful. > (CCG) indicates that one or more of the items requested are invalid for the file’s device type, file type, open status, or other characteristic.
FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) Table 5-9. FILEINQUIRE Item Codes (page 2 of 3) Code Size (bytes) Valid with Number/Name 4 2 both For key sequenced disk files, the generic lock key length. For Enscribe files, if this value has never been set, the key length of the file is returned; for SQL tables, if this value has never been set, or if the set value is the same as the key length of the file, 0 is returned.
FILEINQUIRE Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) Table 5-9. FILEINQUIRE Item Codes (page 3 of 3) Code Size (bytes) Valid with Number/Name 15 8 both Expiration date-time: For DP2 disk files, the time (GMT) beyond which purging of the file will be allowed. The value will be 0 if never set. 16 8 both Last modification date-time: For DP2 disk files, the time (GMT) of the most recent modification to the file.
FILENAME_COMPARE_ Procedure Guardian Procedure Calls (F) FILENAME_COMPARE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The FILENAME_COMPARE_ procedure compares two file names to determine whether they refer to the same object.
Guardian Procedure Calls (F) FILENAME_COMPARE_ Procedure it is a partially qualified file name, the contents of the =_DEFAULTS DEFINE are used to resolve it. See caution under “Considerations.” filename2:length2 input:input STRING .EXT:ref:*, INT:value specifies the second file name that is compared. The value of filename2 must be exactly length2 bytes long.
Guardian Procedure Calls (F) FILENAME_DECOMPOSE_ Procedure FILENAME_DECOMPOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILENAME_DECOMPOSE_ Procedure filename:length input:input STRING .EXT:ref:*, INT:value specifies the valid file name or file-name pattern from which a piece is extracted. The value of filename must be exactly length bytes long. See caution under “Considerations.” output:input piece:maxlen STRING .EXT:ref:*, INT:value returns the extracted piece of filename. maxlen is the length in bytes of the string variable piece. output piece-length INT .
Guardian Procedure Calls (F) <15> = 1 =0 FILENAME_DECOMPOSE_ Procedure Include suffix, that is, the entire portion of filename that follows the part specified by level. Do not include suffix. The default value is 0. input subpart INT:value specifies a single section to be extracted from the level 0 (destination) part of filename. This parameter applies only to process file names, because only a process file name can have a level 0 part with multiple components.
FILENAME_DECOMPOSE_ Procedure Guardian Procedure Calls (F) Examples The following table shows some possible combinations of input values for calls to FILENAME_DECOMPOSE_ and the resulting output values. Note that “suffix” and “prefix” refer to the “include suffix” and “include prefix” options, respectively; “name” refers to a subpart value of 4. Assume that the current default values are “\SYS.$VOL.SUB”. Input filename level $a.b.c 0 $a.b.c 0 f 0 f 0 suffix $VOL.SUB.f f 0 prefix \SYS.
Guardian Procedure Calls (F) FILENAME_EDIT_ Procedure FILENAME_EDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Examples Related Programming Manual Summary The FILENAME_EDIT_ procedure modifies one or more parts of a file name or filename pattern, changing them to a specified value.
Guardian Procedure Calls (F) FILENAME_EDIT_ Procedure Parameters returned value error INT returns a file-system error number indicating the outcome of the operation. filename:maxlen input, output:input STRING .EXT:ref:*, INT:value on input, is the file name or file-name pattern to be edited; on output, contains the edited version of the file name or file-name pattern. The input must be a valid file name or valid file-name pattern; it must not be a DEFINE name.
Guardian Procedure Calls (F) FILENAME_EDIT_ Procedure input options INT:value gives additional options. If omitted, the default value is 0. The fields are: <0:13> Reserved (specify 0). <14> = 1 Remove filename prefix, that is, the entire portion of filename that precedes the part specified by level. =0 <15> = 1 =0 Do not remove prefix. Remove filename suffix, that is, the entire protion of filename that follows the part specified by level. Do not remove suffix.
Guardian Procedure Calls (F) FILENAME_EDIT_ Procedure 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_EDIT_ Procedure Guardian Procedure Calls (F) “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 $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 Modifiers Output filename $a.*.c suffix name $a.* $z:4321.
Guardian Procedure Calls (F) FILENAME_FINDFINISH_ Procedure FILENAME_FINDFINISH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (F) FILENAME_FINDNEXT_ Procedure FILENAME_FINDNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILENAME_FINDNEXT_ Procedure is a file-system error number indicating the outcome of the operation. Error 1 (end of file) indicates that no more names are available. input searchid INT:value is the value that was previously returned by FILENAME_FINDSTART_ to identify the search request. output:input name:maxlen STRING .EXT:ref:*, INT:value contains the name being returned.
Guardian Procedure Calls (F) FILENAME_FINDNEXT_ Procedure specifies a tag value that, when the procedure is used in a nowait manner, is returned in the completion message. If this parameter is omitted, the value 0D is used. If the procedure is not used in a nowait manner, this parameter is ignored. See “Nowait Considerations” for details.
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure FILENAME_FINDSTART_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_ procedure to retrieve individual names.
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure Parameters returned value error INT returns a file-system error number indicating the outcome of the operation. output searchid INT .EXT:ref:1 returns a value that identifies the search request for other file-name inquiry procedures. 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.
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure parameter is omitted or equal to -1, device type is disregarded when selecting file names. See “Device Type Considerations.” device-subtype input INT:value if present and not equal to -1, specifies a device-subtype value to be used in selecting returned names. A name returned by FILENAME_FINDNEXT_ must represent, or must not represent (depending on the value of options), an entity of the specified device subtype.
Guardian Procedure Calls (F) <15> FILENAME_FINDSTART_ Procedure If startname is supplied, and if the first name returned would be startname, then that name is to be skipped and the following name should be returned. The default value is 0. See “Considerations” and “Device Type Considerations.” startname:length input:input STRING .
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure For descriptions of the messages and replies that must be supported to search for qualifier names, refer to the Guardian Procedure Errors and Messages Manual. • • The names returned by FILENAME_FINDNEXT_ are returned in a sequence that is not necessarily alphabetic. (See “Considerations” for the FILENAME_FINDNEXT_ procedure.
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure You can suppress device type simulation by specifying options.<10> = 1. Without device-type simulation, all simulator processes and their subprocesses show a device type of 0 and a subtype of 30. • When searching for only disk files, the search is usually more efficient if you use the device-type parameter to restrict the search to disk devices.
Guardian Procedure Calls (F) FILENAME_FINDSTART_ Procedure Related Programming Manual For programming information about the FILENAME_FINDSTART_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILENAME_MATCH_ Procedure FILENAME_MATCH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
Guardian Procedure Calls (F) -2 -3 -4 -5 FILENAME_MATCH_ Procedure Missing pattern parameter Length error on filename parameter Length error on pattern parameter Bounds error on generic-set parameter filename:length input:input STRING .EXT:ref:*, INT:value is one or more contiguous sections of a valid file name that is to be tested for a match with pattern. The value of filename must be exactly length bytes long.
FILENAME_MATCH_ Procedure Guardian Procedure Calls (F) • FILENAME_MATCH_ does not use the process or system context (as defaulting would require), so it can be used in environments where the PFS (process file segment) is not available. Examples result := FILENAME_MATCH_ ( filename:flen, pattern:plen ); The following 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.
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure FILENAME_RESOLVE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure Syntax for TAL Programmers error := FILENAME_RESOLVE_ ( partialname:length i:i ,fullname:maxlen o:i ,fullname-length ,[ options ] ,[ override-name:length ] i:i ,[ search:length ] i:i ,[ defaults:length ] ); i:i ! ! ! o ! i ! ! ! Parameters returned value error INT is a file-system error number indicating the outcome of the operation. partialname:length input:input STRING .
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure input options INT:value specifies options. If omitted, the default value is 0. The bits, when equal to 1, indicate the following: Bit Meaning <0:7 > Reserved (specify 0). <8> If partialname consists of a simple unqualified disk file name, a DEFINE name is generated to use as the override-name. The generated name is an equal sign (=) followed by partialname. This name convention corresponds to the ASSIGN name convention used by TAL.
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure Bit Meaning <13> If a logical device number (LDEV) appears as part of partialname, FILENAME_RESOLVE_ translates it to the corresponding symbolic device name. A single name part supplied in partialname is to be treated as a subvolume name or pattern. All alphabetic characters in the resolved file name are to be shifted to upper case. If this option is not specified, characters transferred from partialname to fullname are unchanged.
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure override-name:length input:input STRING .EXT:ref:*, INT:value if supplied and if length is not 0, specifies a DEFINE name to be used as the primary input instead of partialname. If used, the value of override-name must be exactly length bytes long. If the DEFINE name does not exist, or if DEFMODE is OFF, partialname is processed as normal. search:length input:input STRING .
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure 4. It applies default values and resolves LDEVs. 5. It changes the result to upper case. • • • • • options.<14> specifies that a single name part supplied in partialname be treated as a subvolume name or pattern. This means that the input string “f” is resolved to the form “\SYS.$VOL.f”. Without this option, “f” would be resolved to “\SYS.$VOL.SUBV.f”. The name $RECEIVE is never expanded with a node name.
Guardian Procedure Calls (F) FILENAME_RESOLVE_ Procedure 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, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILENAME_SCAN_ Procedure FILENAME_SCAN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILENAME_SCAN_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. Possible values include: 0 Syntactically correct name found for count bytes; see description of count parameter 13 The form of the name found is incorrect; also, various program and resource errors string:length input:input STRING .EXT:ref:*, INT:value is a character string to be searched for a valid file name.
Guardian Procedure Calls (F) FILENAME_SCAN_ Procedure entity-level output INT .EXT:ref:1 identifies the class of entity represented by the supplied name based on its syntax. This value corresponds to the “level” of the rightmost name section that appears. Possible values are: -1 0 >0 Node name. Name of device or process without qualifiers. Name of device or process with entity-level qualifiers.
Guardian Procedure Calls (F) FILENAME_SCAN_ Procedure Related Programming Manual For programming information about the FILENAME_SCAN_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FILENAME_TO_OLDFILENAME_ Procedure FILENAME_TO_OLDFILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FILENAME_TO_OLDFILENAME_ Procedure oldstyle-name output INT .EXT:ref:12 returns the internal-format file name. 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.
Guardian Procedure Calls (F) FILENAME_TO_PATHNAME_ Procedure FILENAME_TO_PATHNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters OSS Considerations 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.
Guardian Procedure Calls (F) 4002 FILENAME_TO_PATHNAME_ Procedure filename specifies a Guardian name for an OSS file that either does not exist or has been unlinked but is still open by some process. The corresponding OSS errno value is ENOENT. 4006 The fileset that corresponds to the supplied Guardian name for an OSS file is not mounted. The corresponding OSS errno value is ENXIO. 4013 The caller does not have search access to one of the directories within all of the resulting pathnames.
FILENAME_TO_PATHNAME_ Procedure Guardian Procedure Calls (F) input options INT:value specifies options for the filename parameter: <0:12> Reserved (specify 0). <13> 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. 1 Specifies that pathname always includes the system name in the form /E/system/path.
Guardian Procedure Calls (F) • • • • • • • • • • FILENAME_TO_PATHNAME_ Procedure If the file name contains a node name, it must be that of the node on which the procedure is called. Periods (.) in the Guardian file name are replaced by slashes in the pathname. Alphabetic characters in the pathname are all lower case except for the “G” in “/G.” If the supplied Guardian file name is the Guardian file name of an OSS file, pathname returns the corresponding absolute pathname of the OSS file.
Guardian Procedure Calls (F) FILENAME_TO_PROCESSHANDLE_ Procedure FILENAME_TO_PROCESSHANDLE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The FILENAME_TO_PROCESSHANDLE_ procedure converts a file name to a process handle.
Guardian Procedure Calls (F) FILENAME_TO_PROCESSHANDLE_ Procedure processhandle output INT .EXT:ref:10 returns the process handle of the process designated by filename. 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.
Guardian Procedure Calls (F) FILENAME_UNRESOLVE_ Procedure FILENAME_UNRESOLVE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Examples Related Programming Manual Summary The FILENAME_UNRESOLVE_ procedure accepts a file name as input, deletes lefthand sections that match the default values, and returns a file name that is semantically equivalent to the input file name.
Guardian Procedure Calls (F) FILENAME_UNRESOLVE_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. longname:length input:input STRING .EXT:ref:*, INT:value contains the valid file name or file-name pattern to be acted upon by FILENAME_UNRESOLVE_. The value of longname must be exactly length bytes long. See caution under “Considerations.” shortname:maxlen output:input STRING .
FILENAME_UNRESOLVE_ Procedure Guardian Procedure Calls (F) The contents of defaults are compared with longname to perform the unresolved operation. If used, the value of defaults must be exactly length bytes long and must be in the following form: [[\node.]$volume.]subvolume Omitted name parts are taken from the =_DEFAULTS DEFINE. If this parameter is omitted or if length is 0, the value of the VOLUME attribute of the =_DEFAULTS DEFINE is used. Considerations Caution.
FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Condition Codes 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.
Guardian Procedure Calls (F) FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Parameters input filenum INT:value is the number of an open file that identifies the file whose characteristics are to be returned. You must specify either filenum or file-name; specifying both causes a CCL condition code. current-keyspecifier output INT:ref:1 returns the current key field’s key specifier. This is invalid when you specify the file-name parameter; use filenum.
FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) partition-in-error output INT:ref:1 returns a number from 0 through 15 that indicates the partition in which the latest error occurred for this file. This is invalid when you specify the file-name parameter; use filenum. specifier-of-key-in-error output INT:ref:1 returns the key specifier associated with the latest error occurring with this file.
Guardian Procedure Calls (F) FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) logical-recordlen output INT:ref:1 returns the maximum size of the logical record in bytes. output blocklen INT:ref:1 returns the length, in bytes, of a block of records for the file. key-sequenced-parameters output INT:ref:* is an array where the parameters unique to a key-sequenced file are returned. (Refer to the CREATE procedure for the format of this array.
FILERECINFO Procedure (Superseded by FILE_GETINFOLISTBYNAME_ Procedure ) Guardian Procedure Calls (F) Considerations • The FILERECINFO procedure is used to determine whether a file is a queue file or an ordinary key-sequenced file. This procedure should not be used for determining the value of the current key of the queue file, because the current key position is not maintained for queue files. The current-keyvalue parameter that would be returned for a queue file is undefined.
FIXSTRING Procedure Guardian Procedure Calls (F) 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.
FIXSTRING Procedure Guardian Procedure Calls (F) Parameters input template STRING:ref:* is the character string to be used as a modification template. There are three basic subcommands that you can use in template: replacement, insertion, and deletion. In addition, replacement can be either explicit (a subcommand beginning with “R”) or implicit (a subcommand beginning with any nonblank character other than “R,” “I,” or “D”). The form of template is: template = { subcommand // ...
Guardian Procedure Calls (F) FIXSTRING Procedure modification-status output INT:ref:1 returns an integer value as follows: 0 1 No change was made to data. A replacement, insertion, or deletion was performed on data (see “Considerations”). Condition Code Settings < (CCL) indicates that one or more of the required parameters is missing. = (CCE) indicates that the operation completed successfully.
Guardian Procedure Calls (F) FIXSTRING Procedure This subcommand inserts a string from template into data preceding the character corresponding to the “I”. The insertion-string is terminated by the end of template or by a “//” sequence in template. Trailing blanks are considered part of the insertion string (that is, they are not ignored). • When data is truncated The maximum-data-len serves to protect data residing past the end of the data string.
FNAME32COLLAPSE Procedure (Superseded) Guardian Procedure Calls (F) FNAME32COLLAPSE Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. FNAME32COLLAPSE converts the 32-character file name used by the Distributed Name Service to external format for display.
Guardian Procedure Calls (F) FNAME32COLLAPSE Procedure (Superseded) output extname STRING .EXT:ref:35 contains, on return, the external form of intname: \sysname.$volume.subvol.file-id Considerations • • The caller must pass a valid subsystem object name in intname. Invalid names cause unpredictable results. If a parameter is missing or a bounds error occurs on a parameter, length will contain 0.
Guardian Procedure Calls (F) FNAME32EXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure ) FNAME32EXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (F) FNAME32EXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure ) output intname STRING .EXT:ref:32 is an array of 32 characters where FNAME32EXPAND returns the expanded file name. This array can be the same array as extname. input defaults 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.
Guardian Procedure Calls (F) FNAME32TOFNAME Procedure (Superseded) FNAME32TOFNAME Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. FNAME32TOFNAME converts a file name from the 32-character format used by the Distributed Name Service (DNS) to its internal format.
Guardian Procedure Calls (F) FNAME32TOFNAME Procedure (Superseded) 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.
Guardian Procedure Calls (F) FNAMECOLLAPSE Procedure (Superseded by OLDFILENAME_TO_FILENAME_ Procedure) FNAMECOLLAPSE Procedure (Superseded by OLDFILENAME_TO_FILENAME_ 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. The FNAMECOLLAPSE procedure converts a file name from internal to external form.
Guardian Procedure Calls (F) FNAMECOLLAPSE Procedure (Superseded by OLDFILENAME_TO_FILENAME_ Procedure) external-name output STRING:ref:26 or STRING:ref:34 returns the external form of internal-name. If internal-name is a local file name, external-name contains a maximum of 26 bytes; if a network name is converted, external-name contains a maximum of 34 bytes. (See the FNAMEEXPAND procedure.
Guardian Procedure Calls (F) FNAMECOMPARE Procedure (Superseded by FILENAME_COMPARE_ FNAMECOMPARE Procedure (Superseded by FILENAME_COMPARE_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Examples Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (F) 1 FNAMECOMPARE Procedure (Superseded by FILENAME_COMPARE_ 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. input filename1 INT:ref:12 is the first file name that is compared.
Guardian Procedure Calls (F) FNAMECOMPARE Procedure (Superseded by FILENAME_COMPARE_ -13 An illegal file name specification for either file name is made. -14 The device does not exist. Only one of the file names is passed in logical device number format (requiring a check of the device table), and the file name represents a device connected to a remote node. -18 No such system is defined in this network.
Guardian Procedure Calls (F) FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and FILENAME_RESOLVE_ 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.
Guardian Procedure Calls (F) FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and external-filename input STRING:ref:27 or STRING:ref:35 is the file name to be expanded. The file name must be in the form: [\sysname.]file-name or definename followed by a delimiter, and where file-name is in one of these forms: [$volname.][subvol-name.]file-id $processname[.#1st-qualif-name[.
FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and Guardian Procedure Calls (F) [0:7] corresponds directly to word[1:8] of the command interpreter startup message. Refer to the Guardian Procedure Errors and Messages Manual for the startup message format. Considerations • Expanding network file names FNAMEEXPAND converts local file names to local names and network file names to network names.
FNAMEEXPAND Procedure (Superseded by FILENAME_SCAN_ Procedure and Guardian Procedure Calls (F) • $devname returns as: [0:11] • $devname (blank-fill) $ldevnum returns as: [0:11] $ldevnum (blank-fill) If any of the forms described above are preceded by “\sysname,” the result is as given above, except that “\sysnum” replaces “$” in the result. • definename returns as: [0:11] definename (blank-fill) Any other file name is invalid.
Guardian Procedure Calls (F) FNAMETOFNAME32 Procedure (Superseded) FNAMETOFNAME32 Procedure (Superseded) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. FNAMETOFNAME32 converts a file name from the 12-word internal format to the 32-character Distributed Name Service (DNS) format.
Guardian Procedure Calls (F) FNAMETOFNAME32 Procedure (Superseded) output fname32 STRING .EXT:ref:32 contains, on return, the file name in DNS format. If status is returned as zero, the contents of this array have not been modified by the procedure. Considerations • • If fname is in network format and the system number specified is not currently defined to the network, FNAMETOFNAME32 returns 0 to indicate that the file name cannot be converted.
Guardian Procedure Calls (F) FORMATCONVERT[X] Procedure FORMATCONVERT[X] Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FORMATCONVERT[X] Procedure Syntax for TAL Programmers status := FORMATCONVERT[X] ( iformat ,iformatlen ,eformat ,eformatlen ,scales ,scale-count ,conversion ); ! ! ! ! ! ! ! o i i i o i,o i Parameters returned value status INT is a value indicating the outcome of FORMATCONVERT[X]: >0 Indicates successful conversion. The value is the number of bytes in the converted format (iformat). =0 Indicates iformatlen was insufficient to hold the entire converted format.
FORMATCONVERT[X] Procedure Guardian Procedure Calls (F) input eformat STRING:ref:* (Use with FORMATCONVERT) STRING .EXT:ref:* (Use with FORMATCONVERTX) is the format string in external (ASCII) form. input eformatlen INT:value is the length, in bytes, of the eformat string. output scales INT:ref:* INT .EXT:ref:* (Use with FORMATCONVERT) (Use with FORMATCONVERTX) is an integer array.
Guardian Procedure Calls (F) FORMATCONVERT[X] Procedure input conversion INT:value Specifies the type of conversion to be done: 0 Check validity of format only. No data is stored into iformat. The scale information is stored in the scales array. 1 Produce expanded form with modifiers and decorations. This requires additional storage space, but the execution time is half that of version 2 (below). The size required is approximately 10 times eformatlen.
Guardian Procedure Calls (F) FORMATDATA[X] Procedure FORMATDATA[X] Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (F) FORMATDATA[X] 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 returned value error INT:value indicates the outcome of the call.
FORMATDATA[X] Procedure Guardian Procedure Calls (F) output length INT:ref:* INT .EXT:ref:* (Use with FORMATDATA) (Use with FORMATDATAX) is an array that must have at least as many elements as there are buffers in the buffer array on output. FORMATDATA[X] stores the highest referenced character position in each buffer in the corresponding length element. If a buffer is not accessed, -1 is stored for that buffer and for all succeeding ones.
FORMATDATA[X] Procedure Guardian Procedure Calls (F) <3> P-Relative (iformat array) 0 1 <2> The iformat array address is G-relative. The iformat array address is P-relative. List-directed (refer to the Guardian Programmer’s Guide for information about list-directed operations) 0 1 Apply the format-directed operation. Apply the list-directed operation. <1:0> Reserved, specify 0 Considerations • • A passed P-relative iformat array must be in the same code segment as the call.
FORMATDATA[X] Procedure Guardian Procedure Calls (F) datatype is the type and scale factor of the element: bits <8:15>: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 String Numeric string unsigned Integer(16) signed Integer(16) unsigned Integer(32) signed Integer(32) unsigned Integer(64) signed Not used Real(32) Complex(32*2) Real(64) Complex(64*2) Numeric string, sign trailing, embedded Numeric string, sign trailing, separate Numeric string, sign leading, embedded Numeric string, sign l
Guardian Procedure Calls (F) FORMATDATA[X] Procedure Example ERROR := FORMATDATAX ( BUFFERS , BUF^LEN , NUM^BUFS , BUF^LENS , WFORMAT , VLIST , 4 , 0 ); Related Programming Manual For programming information about the FORMATDATA procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (F) FP_IEEE_DENORM_GET_ Procedure FP_IEEE_DENORM_GET_ Procedure Summary The FP_IEEE_DENORM_GET_ procedure reads the IEEE floating-point denormalization mode. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include fp_ieee_denorm FP_IEEE_DENORM_GET_ (void); Syntax for TAL Programmers ?source $system.
Guardian Procedure Calls (F) FP_IEEE_DENORM_SET_ Procedure FP_IEEE_DENORM_SET_ Procedure Summary The FP_IEEE_DENORM_SET_ procedure sets the IEEE floating-point denormalization mode. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include
Guardian Procedure Calls (F) FP_IEEE_DENORM_SET_ Procedure Consideration Operations with denormalization disabled can cause problems by causing a gap around zero in the distribution of values that can be represented. With denormalization disabled, the results will not comply with the IEEE standard and might not match results on any other system.
Guardian Procedure Calls (F) FP_IEEE_ENABLES_GET_ Procedure FP_IEEE_ENABLES_GET_ Procedure 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 the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors.
Guardian Procedure Calls (F) FP_IEEE_ENABLES_GET_ Procedure Considerations • • • • • A constant named FP_IEEE_ALL_ENABLES is equivalent to a combination of the mask bits to enable traps for all the exceptions. In some cases, the conditions that cause a trap are slightly different from the conditions that cause the corresponding exception flag to be set. When a trap happens, a SIGFPE signal is raised, and the corresponding signal handler is called.
Guardian Procedure Calls (F) FP_IEEE_ENABLES_SET_ Procedure FP_IEEE_ENABLES_SET_ Procedure 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 the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors.
Guardian Procedure Calls (F) • • FP_IEEE_ENABLES_SET_ Procedure When you enable traps, you will not get a trap from a left-over status; you will trap only from operations that happen after you enable the traps. See Considerations on page 5-255 for more considerations for this procedure. Examples C Example #include
FP_IEEE_ENV_CLEAR_ Procedure Guardian Procedure Calls (F) FP_IEEE_ENV_CLEAR_ Procedure 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.
Guardian Procedure Calls (F) FP_IEEE_ENV_CLEAR_ Procedure 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.
Guardian Procedure Calls (F) FP_IEEE_ENV_RESUME_ Procedure FP_IEEE_ENV_RESUME_ Procedure 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 the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors.
Guardian Procedure Calls (F) FP_IEEE_EXCEPTIONS_GET_ Procedure FP_IEEE_EXCEPTIONS_GET_ Procedure Summary The FP_IEEE_EXCEPTIONS_GET_ procedure reads the IEEE floating-point exception mask. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include
FP_IEEE_EXCEPTIONS_GET_ Procedure Guardian Procedure Calls (F) Exception flag values of Exceptions are: Value Cause FP_IEEE_INVALID Arithmetic calculations using either positive or negative infinity as an operand, zero divided by zero, the square root of -1, the rem function with zero as a divisor (which causes divide by zero), comparisons with invalid numbers, or impossible binary-decimal conversions. FP_IEEE_DIVBYZERO Computing x/0, where x is finite and nonzero.
Guardian Procedure Calls (F) FP_IEEE_EXCEPTIONS_GET_ Procedure TAL Example proc DOCOMPUTATION; external; ?nolist ?source $system.system.
Guardian Procedure Calls (F) FP_IEEE_EXCEPTIONS_SET_ Procedure FP_IEEE_EXCEPTIONS_SET_ Procedure Summary The FP_IEEE_EXCEPTIONS_SET_ procedure sets the IEEE floating-point exception mask. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include
FP_IEEE_EXCEPTIONS_SET_ Procedure Guardian Procedure Calls (F) Exception flag values of NewFlags are: FP_IEEE_INVALID Arithmetic calculations using either positive or negative infinity as an operand, zero divided by zero, the square root of -1, the rem function with zero as a divisor (which causes divide by zero), comparisons with invalid numbers, or impossible binary-decimal conversions. FP_IEEE_DIVBYZERO Computing x/0, where x is finite and nonzero.
FP_IEEE_ROUND_GET_ Procedure Guardian Procedure Calls (F) FP_IEEE_ROUND_GET_ Procedure Summary The FP_IEEE_ROUND_GET_ procedure reads the current rounding mode. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include p_ieee_round FP_IEEE_ROUND_GET_(void); Syntax for TAL Programmers ?source $system.system.
FP_IEEE_ROUND_SET_ Procedure Guardian Procedure Calls (F) FP_IEEE_ROUND_SET_ Procedure Summary The FP_IEEE_ROUND_SET_ procedure sets the current rounding mode. Note. This procedure is supported in the G06.06 RVU and all subsequent G-series RVUs. IEEE floating-point is available on all S-series processors except S70000 servers with NSR-G processors. Syntax for C Programmers #include void FP_IEEE_ROUND_SET_( fp_ieee_round new_mode ); Syntax for TAL Programmers ?source $system.system.
6 Guardian Procedure Calls (G) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter G. Table 6-1 lists all the procedures in this section. Table 6-1.
GETCPCBINFO Procedure Guardian Procedure Calls (G) 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).
Guardian Procedure Calls (G) GETCPCBINFO Procedure 3 Safeguard-authenticated logoff state; returns 1 in cpcb-info if the Safeguard-authenticated logon flag is set but the process has logged off. 4 Inherited-logon flag; returns 1 in cpcb-info if the logon was inherited by the process. 5 Stop-on-logoff flag; returns 1 in cpcb-info if the process is to be stopped when it requests to be placed in the logged-off state.
Guardian Procedure Calls (G) GETCPCBINFO Procedure Example CALL GETCPCBINFO ( REQUEST^ID , PCB^INFO , IN^LENGTH , OUT^LENGTH , ERROR^REQUEST ); Guardian Procedure Calls Reference Manual—522629-013 6 -4
Guardian Procedure Calls (G) GETCRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ 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.
Guardian Procedure Calls (G) GETCRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ output process-id INT:ref:4 is the 4-word array where GETCRTPID returns the CRTPID (or process ID) of the process specified by cpu,pin. The process-id is returned in local form, that is, [0:2] Process name or creation timestamp [3].<0:3> Reserved .<4:7> processor number where the process is executing .
Guardian Procedure Calls (G) GETDEVNAME Procedure (Superseded by DEVICE_GETINFOBYLDEV_ GETDEVNAME Procedure (Superseded by DEVICE_GETINFOBYLDEV_ Procedure (Superseded on G-series Releases) or FILENAME_FINDNEXT_ 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.
Guardian Procedure Calls (G) GETDEVNAME Procedure (Superseded by DEVICE_GETINFOBYLDEV_ Syntax for TAL Programmers status := GETDEVNAME ( ldevnum ,devname ,[ sysnum ] ,[ devtype ] ,[ devsubtype ] ); ! ! ! ! ! i,o o i i i Parameters returnedvalue status INT indicates the outcome of the call. The values of status can be: Successful; the name of the designated logical device is returned in devname. The designated logical device does not exist.
GETDEVNAME Procedure (Superseded by DEVICE_GETINFOBYLDEV_ Guardian Procedure Calls (G) output devname INT:ref:4 returns the device name or volume name of the designated device, if it exists, or the next higher (numerically) logical device if the designated device does not exist. The devname remains unchanged if no higher logical device exists. input sysnum INT:value specifies the system (in a network) that is searched for ldevnum. If omitted, the local system is assumed.
Guardian Procedure Calls (G) • GETDEVNAME Procedure (Superseded by DEVICE_GETINFOBYLDEV_ 1 word identifying the node number and 3 words of zero for example, "\n",0,0,0 (n is the value in SYSNUM) Example INT INT INT STRING INT system; !target system ldev; !ldev to start search name [0:3] := [" "]; names = name; status; ! get next disk name DO BEGIN ldev := ldev + 1; status := getdevname ( ldev, name, system, 3 ); END UNTIL (status '>' 1) OR (name AND name <> " " AND NOT (names = "\" AND (name[1] = " "
Guardian Procedure Calls (G) GETINCREMENTEDIT Procedure GETINCREMENTEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (G) GETINCREMENTEDIT Procedure Related Programming Manual For programming information about the GETINCREMENTEDIT procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (G) GETPOOL Procedure (Superseded by POOL_* Procedures) GETPOOL Procedure (Superseded by POOL_* Procedures) Summary Considerations 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. *POOL procedures are replaced by POOL_* procedures. There is no one-for-one replacement.
Guardian Procedure Calls (G) GETPOOL Procedure (Superseded by POOL_* Procedures) input,output pool-head INT .EXT:ref:19 is the pool head previously defined by a call to DEFINEPOOL. input block-size INT(32):value is the size, in bytes, of the memory obtained from the pool. This number cannot be greater than %377770D. To check data structures without getting any memory from the pool, set block-size to zero.
Guardian Procedure Calls (G) GETPOOL_PAGE_ Procedure (H-Series RVUs Only) GETPOOL_PAGE_ Procedure (H-Series RVUs Only) Summary Considerations for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (G) GETPOOL_PAGE_ Procedure (H-Series RVUs Only) input block-size INT(32):value is the size, in bytes, of the memory obtained from the pool. This number cannot be greater than %377770D. To check data structures without getting any memory from the pool, set block-size to zero. Condition Code Settings < (CCL) indicates that block-size is out of range, or that the data structures are invalid; -1D is returned.
Guardian Procedure Calls (G) GETPOSITIONEDIT Procedure GETPOSITIONEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (G) GETPOSITIONEDIT Procedure Related Programming Manual For programming information about the GETPOSITIONEDIT procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (G) GETPPDENTRY Procedure (Superseded by PROCESS_GETPAIRINFO_ 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.
GETPPDENTRY Procedure (Superseded by PROCESS_GETPAIRINFO_ Guardian Procedure Calls (G) output ppd INT:ref:9 is an array where GETPPDENTRY returns the nine-word DCT entry specified by the given index and sysnum. Its format is: Process name (in local form) [0:2] [3].<0:7> processor of primary process [3].<8:15> PIN of primary process [4].<0:7> processor of backup process if it is a process pair. (This is 0 if there is no backup.) [4].<8:15> PIN of backup process, if it is a process pair.
Guardian Procedure Calls (G) GETPPDENTRY Procedure (Superseded by PROCESS_GETPAIRINFO_ Considerations • Checking the DCT entry If index is not currently being used, GETPPDENTRY returns CCE and sets ppd to zeros. To check for all conditions, an application could contain the following code: CALL GETPPDENTRY( INDEX^NUM , SYS^NUM , PROCESS^PAIR^DESCRIPT ); IF < THEN ... ; ! system unavailable. IF > THEN ! STOP, no more DCT entries available. IF = AND PROCESS^PAIR^DESCRIPT THEN ... ! found an entry.
Guardian Procedure Calls (G) GETREMOTECRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ GETREMOTECRTPID 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.
GETREMOTECRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ Guardian Procedure Calls (G) output process-id INT:ref:4 is the 4-word array where GETREMOTECRTPID returns the process ID of the process specified by cpu,pin. The process-id is returned as follows: Process name or creation timestamp [0:2] [3].<0:3> Reserved .<4:7> processor number where the process is executing .
Guardian Procedure Calls (G) GETREMOTECRTPID Procedure (Superseded by PROCESS_GETINFOLIST_ Considerations You cannot use GETREMOTECRTPID for high-PIN processes because a high PIN cannot fit into cpu,pin or process-id.
GETSYNCINFO Procedure (Superseded by FILE_GETSYNCINFO_ Procedure) Guardian Procedure Calls (G) 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.
Guardian Procedure Calls (G) GETSYNCINFO Procedure (Superseded by FILE_GETSYNCINFO_ Procedure) Parameters input filenum INT:value is the number of an open file that identifies the file whose sync block is obtained. output sync-block INT:ref:* returns the synchronization block for this file. The size, in words, of sync-block is determined as follows: • • • • • For unstructured disk files, size = 8 words. For ENSCRIBE structured files, size in words = 11 + (longest alt key len + pri key len + 1) / 2.
Guardian Procedure Calls (G) GETSYNCINFO Procedure (Superseded by FILE_GETSYNCINFO_ Procedure) If an out-of-bounds application buffer address parameter is specified in the GETSYNCINFO call (that is, a pointer to the buffer has an address that is outside of the data area of the process) or if the buffer lies within the data area that is used by GETSYNCINFO, then the call returns with file-system error 22.
Guardian Procedure Calls (G) GETSYSTEMNAME Procedure (Superseded by NODENUMBER_TO_NODENAME_ Procedure ) GETSYSTEMNAME Procedure (Superseded by NODENUMBER_TO_NODENAME_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary The GETSYSTEMNAME procedure supplies the system name associated with a system number. Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (G) GETSYSTEMNAME Procedure (Superseded by NODENUMBER_TO_NODENAME_ Procedure ) The specified system is the local system, so there is no line handler logical device number to return. 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. sysnum input INT:value {0:254} is the number of the system; the name is returned in sysname.
Guardian Procedure Calls (G) GETSYSTEMSERIALNUMBER Procedure GETSYSTEMSERIALNUMBER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary The GETSYSTEMSERIALNUMBER procedure returns the system serial number of the caller’s system as an ASCII character string of numerals.
GETSYSTEMSERIALNUMBER Procedure Guardian Procedure Calls (G) output string-length INT .EXT:ref:1 returns the number of numerals in the serial number that is returned in stringbuffer. Example This example calls GETSYSTEMSERIALNUMBER and displays the result.
GIVE^BREAK Procedure Guardian Procedure Calls (G) GIVE^BREAK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
GIVE^BREAK Procedure Guardian Procedure Calls (G) input file-fcb INT:ref:* identifies the file returning BREAK to the previous owner. If BREAK is not owned, this call is ignored. Example CALL GIVE^BREAK ( OUT^FILE ); ! return BREAK to ! previous owner. Related Programming Manual For programming information about the GIVE^BREAK procedure, refer to the Guardian Programmer’s Guide.
GROUP_GETINFO_ Procedure Guardian Procedure Calls (G) GROUP_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. Syntax for C Programmers Note.
Guardian Procedure Calls (G) GROUP_GETINFO_ Procedure returns a file-system error number indicating the outcome of the call. Common errors returned are: 0 No error. 11 Record not in file. The specified group name or group ID is undefined. 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.
Guardian Procedure Calls (G) GROUP_GETINFO_ Procedure on input, if group-curlen is 0 or omitted, specifies the group ID for which information is to be returned. On output, if group-name is specified and group-curlen is not 0, this parameter returns the group ID corresponding to the specified group name. group-id is a value in the range 0 through 65,535. output is-auto-delete INT .EXT:ref:1 indicates whether the specified group is automatically deleted when it no longer contains members.
GROUP_GETNEXT_ Procedure Guardian Procedure Calls (G) GROUP_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (G) GROUP_GETNEXT_ Procedure 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. The value specified in group-curlen is greater than the value specified in group-maxlen.
Guardian Procedure Calls (G) GROUP_GETNEXT_ Procedure Example ! obtain all group names i := 0; curlen := 0; DO error := GROUP_GETNEXT_ ( name:MAXLEN, curlen); group^list[i] ’:=’ name for curlen BYTES; i := i + 1; UNTIL (error <> 0); Guardian Procedure Calls Reference Manual—522629-013 6- 39
GROUPIDTOGROUPNAME Procedure (Superseded by GROUP_GETINFO_ Procedure ) Guardian Procedure Calls (G) GROUPIDTOGROUPNAME Procedure (Superseded by GROUP_GETINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (G) GROUPIDTOGROUPNAME Procedure (Superseded by GROUP_GETINFO_ Procedure ) Parameters input, output id-name INT:ref:4 On input, contains the group ID to be converted to a group name. The group ID is passed in the form: id-name.
Guardian Procedure Calls (G) GROUPMEMBER_GETNEXT_ Procedure GROUPMEMBER_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (G) GROUPMEMBER_GETNEXT_ Procedure 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 all parameters. 590 Bad parameter value.
Guardian Procedure Calls (G) GROUPMEMBER_GETNEXT_ Procedure Considerations • • • Aliases are defined only when Safeguard is installed. Names are not returned in any particular order, and the order can change from one RVU to the next. Naming rules in the Guardian environment are more restrictive than those in the OSS environment. Example ! obtain all names associated with a particular group ID i := 0; user^list.len[i] := 0; DO error := GROUPMEMBER_GETNEXT_ (group^id, user^list.
Guardian Procedure Calls (G) GROUPNAMETOGROUPID Procedure (Superseded by GROUP_GETINFO_ Procedure ) GROUPNAMETOGROUPID Procedure (Superseded by GROUP_GETINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (G) GROUPNAMETOGROUPID Procedure (Superseded by GROUP_GETINFO_ Procedure ) The group name must be input in uppercase. On return, name-id contains the group ID associated with the group name in the form: name-id.<8:15> = group ID {0:255} Condition Code Settings < (CCL) indicates that name-id is out of bounds, or that an I/O error occurred when the procedure accessed the $SYSTEM.SYSTEM.USERID file. = (CCE) indicates that the designated group ID is returned.
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 7-1 lists all the procedures in this section. Table 7-1.
HALTPOLL Procedure Guardian Procedure Calls (H-K) HALTPOLL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Example Related Programming Manuals Summary The HALTPOLL procedure is normally used to stop continuous polling.
Guardian Procedure Calls (H-K) HEADROOM_ENSURE_ Procedure FNUM is the integer returned from the call to FILE_OPEN_ or OPEN that opened the particular communication line. HALTPOLL forces the immediate termination of an outstanding nowait read operation within a point-to-point station, or it stops any polling that is in progress within a multipoint station. Related Programming Manuals For programming information about the HALTPOLL procedure, refer to the data communication manuals.
Guardian Procedure Calls (H-K) HEADROOM_ENSURE_ Procedure Syntax for TAL Programmers ret-val := HEADROOM_ENSURE_ ( room ); ! i Parameters returned value ret-val INT(32) returns the number of bytes between the current stack pointer and the stack limit if room is <= 0D. If room is > 0D, ret-val indicates the outcome of the operation.
Guardian Procedure Calls (H-K) HEADROOM_ENSURE_ Procedure system.
HEAPSORT Procedure Guardian Procedure Calls (H-K) 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.
Guardian Procedure Calls (H-K) HEAPSORT Procedure 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 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 .
Guardian Procedure Calls (H-K) HEAPSORTX_ Procedure HEAPSORTX_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (H-K) HEAPSORTX_ Procedure indicates the outcome of the operation. It returns one of the following values: 0 29 590 632 Array has been successfully sorted. Required parameter is missing. Invalid parameter supplied. Insufficient stack space for temporary variable (see “Considerations”). input, output array INT .EXT:ref:* contains equal-sized elements to be sorted. num-elements input INT(32):value is the number of elements in array.
Guardian Procedure Calls (H-K) HEAPSORTX_ Procedure If this parameter is specified, and not equal to 0D, the sort builds an array of pointers in the area supplied by this parameter. It is these pointers that are rearranged as the sort progresses. Only when the sort is complete is the actual data supplied in the array parameter rearranged. If this parameter is omitted or specified as 0D, the sort works directly on the data supplied in the array parameter.
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure HIST_FORMAT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Code Example Traces: Case 1 Example Traces: Case 2 Example Traces: Case 3 Example Traces: Case 4 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.
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) -2 HIST_BAD_WIDTH The value of the limit parameter is less than the minimum width for output defined by the HIST_MinWidth literal in the HHISTRY header file. -9 HIST_BAD_WORKSPACE The workspace structure has an invalid version identifier. This error can occur if HIST_FORMAT_ is called without first calling the HIST_INIT_ procedure or if the workspace structure has become corrupted. -10 HIST_BAD_FORMAT_CALL Nothing to format.
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure library RISC (SLr), or millicode (milli). For TNS code, it shows the code segment index (for example, UL.00). For named native shared run-time libraries (SRLs), it shows the SRL name (not its object file name). HF_Context Shows the RISC register contents whenever a full context is available (for example, when a signal is generated).
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) If a larger set of RISC registers is being displayed because of the HF_Context or HF_Registers options, the HF_LocLineRISC information is redundant and not shown. HF_LocLineTNS For procedures executing in TNS or accelerated mode, shows the values of P, E, L, and S (when available), in octal. HF_Name Shows the procedure name if available. If the name is not available, the action depends upon the rest of the FormatSelect field.
Guardian Procedure Calls (H-K) • • • • • HIST_FORMAT_ Procedure 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.
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) HO_ShowProtected, and HO_NoSuppress, the trace would look something like this: Returned Text Explanation HANDLER + 0x28 (UCr) Indicates the current procedure (that is, the signal handler) and the offset. PK_SIG_HANDLER_JACKET_ + 0x54 (SLr) Indicates the procedure that called the handler and the offset of the call. The system procedure that called the handler is considered a transition frame and is suppressed by default.
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) Returned Text Explanation ... Denotes one or more stack frames that are not shown; although a complete chain of procedure calls did take place, they are not all displayed. In this case, USER_PROC did not call PRIV_PROC_ directly; the activation record of the original CALLABLE procedure (and perhaps others in the chain of calls leading to the failure) was discarded as the signal was delivered to the user’s handler.
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure To specify a nondefault format selection, place an assignment to workspace.FormatSelect after the HIST_INIT_ call but outside the WHILE loop. Example Traces: Case 1 The following traces are produced by a procedure named xtracer called from a native signal handler. xtracer starts the trace by calling the HIST_INIT_ and HIST_FORMAT_ procedures. A SIGSEGV signal is generated in a procedure that is invoked from a CALLABLE procedure.
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) An example trace in the TNS/E environment: options = HO_Init_Here + HO_ShowProtected FormatSelect = HF_trace xtracer + 0x110 (UCr) handler + 0x220 (UCr) --doer + 0x170 (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) + HF_Context.
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure 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: 00000000000
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) An example trace in the TNS/R environment: xtracer + 0x60 (UCr) pc=0x70000B20 VFP=0x4FFFFAF0 FP=sp=0x4FFFF878 handler + 0x170 (UCr) pc=0x7000218C VFP=0x4FFFFB20 FP=sp=0x4FFFFAF0 --doer + 0x5C (UCr) pc=0x70002290 VFP=0x5FFFFEB8 FP=sp=0x5FFFFE88 ...
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure Example Traces: Case 2 The following trace results from a sequence of events similar to case 1, except that the CALLABLE procedure named caller attempts to divide by zero before invoking doer. The output does not include an ellipsis because the trap occurs in a CALLABLE procedure called by a nonprivileged procedure. For this trace: • • options equals HO_Init_Here + HO_ShowProtected + HO_NoSuppress. FormatSelect equals HF_trace (the default value).
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) 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_.
Guardian Procedure Calls (H-K) HIST_FORMAT_ Procedure 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 E000
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) An example trace in the TNS/E environment: (millicode example) options = HO_Init_uContext + HO_NoSuppress FormatSelect = HF_trace + LocLineIPF copyData + 0x6C51 (Milli) pc:%h0000000000000000 psp:0x000000006FFFFC10 _SharedMilli_MOVB_FWD + 0x2B0 (Milli) pc:%h0000000000000000 psp:0x000000006FFFFD00 doer + 0x1A0 (UCr) pc:0x0000000070001960 psp:0x000000006FFFFD80 HIST_TEST_ACTOR + 0xC0 (UCr) pc:0x0000000070001D60 psp:0x000000006FFFFDF0 main + 0xB10 (UCr) pc
HIST_FORMAT_ Procedure Guardian Procedure Calls (H-K) Note that, like the S register, the accelerated program counter (pc) value is known only at the point of the HIST_INIT_ call. SHTC.xtracer + %37 (acc UC.00) pc=%h70420D84 P=%001314 E=%000200:T,UC.00 main + %740 (UC.00) P=%001071 E=%000200:T,UC.00 L=%023453 _MAIN + %32 (UC.00) P=%000125 E=%000200:T,UC.
Guardian Procedure Calls (H-K) HIST_GETPRIOR_ Procedure HIST_GETPRIOR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. See the HIST_INIT_ procedure for an overview of how HIST_INIT_, HIST_FORMAT_, and HIST_GETPRIOR_ can be used together to perform stack tracing.
Guardian Procedure Calls (H-K) HIST_GETPRIOR_ Procedure 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. input, output workspace INT .EXT:ref:(HISTWORKSPACE_TEMPLATE) identifies the context and format of the process state to be displayed by the next HIST_FORMAT_ procedure call.
Guardian Procedure Calls (H-K) HIST_INIT_ Procedure HIST_INIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers 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_ Procedure Guardian Procedure Calls (H-K) Syntax for TAL Programmers ?SOURCE $SYSTEM.SYSTEM.HHISTRY error := HIST_INIT_ ( workspace ,version ,options ,context ); !i,o !i !i !i Parameters returned value error INT indicates the outcome of the operation: 0 HIST_OK The procedure terminated normally. 1 HIST_DONE The procedure has reached the base of the stack trace. -3 HIST_BAD_VERSION An invalid value was specified for the version parameter.
Guardian Procedure Calls (H-K) HIST_INIT_ Procedure input, output workspace INT .EXT:ref:(HISTWORKSPACE_TEMPLATE) identifies the workspace area to be initialized by this procedure with information that establishes how the stack trace will proceed. This area must be allocated before you call this procedure. The address of this workspace area is passed to subsequent calls to the HIST_FORMAT_ and HIST_GETPRIOR_ procedures.
HIST_INIT_ Procedure Guardian Procedure Calls (H-K) A subsequent call to HIST_FORMAT_ returns context for that location. The address must point to a code location, but that location can contain TNS instructions or RISC instructions. To find out what is at a TNS address, you must first convert the TNS address into a RISC address. See the System Description Manual for details on address translation. 10 HO_Init_FuncPtr uses a 32-bit function pointer for the context.
HIST_INIT_ Procedure Guardian Procedure Calls (H-K) <7> HO_OneLine modifies some formatting options to optimize the display of information in a single output line. It does not, however, ensure that all the information fits in one line. input context EXTADDR:value designates the procedure context for display. The type of context whose address appears in context must match the context type specified in the options parameter bits <13:15> (the HO_Init_* value) as follows: If options.<13:15> specifies...
Guardian Procedure Calls (H-K) HIST_INIT_ Procedure HF_Offset, or HF_CodeSpace. These are all selected by default. The user can assign a subset. See HIST_FORMAT_ for a description of workspace.FormatSelect options. • Protected contexts When a run-time event that requires immediate attention, such as a hardware trap, causes a signal to be generated, the uContext structure presented to the signal handler contains either one or two contexts.
Guardian Procedure Calls (H-K) INCREMENTEDIT Procedure 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).
Guardian Procedure Calls (H-K) INCREMENTEDIT Procedure specified as 1000 times the line number increment value. If this parameter is omitted, the value 1000 is used. The possible EDIT line numbers are 0, 0.001, 0.002, ... 99999.999. Example In the following example, INCREMENTEDIT sets the line number increment value to 10. INT(32) increment := 10000D; . .
INITIALIZEEDIT Procedure Guardian Procedure Calls (H-K) INITIALIZEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (H-K) INITIALIZEEDIT Procedure the EFS on the specified device, the name of the caller’s swap volume is used. (The swap volume of the calling program is normally the same as its object file volume, unless the SWAP option of the TACL RUN command was invoked.) If the EFS cannot be allocated on the caller’s swap volume, INTIALIZEEDIT then tries every disk volume in the system until it succeeds.
Guardian Procedure Calls (H-K) INITIALIZEEDIT Procedure Nowait Considerations IOEdit always returns to the caller with the operation finished. In this sense, it does not perform nowait I/O. Note that for write operations, the operation is considered finished when the data is in the IOEdit buffer and might not yet have been passed to the file system. The nowait-option parameter controls how this buffering is done.
INITIALIZER Procedure Guardian Procedure Calls (H-K) INITIALIZER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
INITIALIZER Procedure Guardian Procedure Calls (H-K) input rucb INT:ref:* is a table containing pointers to FCBs (see “Considerations”). output passthru INT:ref:* is an array where the startupproc, paramsproc, and assignproc procedures can return information to or receive information from the caller of INITIALIZER.
Guardian Procedure Calls (H-K) INITIALIZER Procedure match INT:value is the match count. 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. If a match is found, the information from the assign message is put into the FCBs, and the match count is incremented. If this is not an assign message or if the rucb parameter is not passed, the match count is always 0.
Guardian Procedure Calls (H-K) INITIALIZER Procedure input num^fcbs INT:value specifies the number of FCBs passed in the fcb^array parameter. This parameter is required for native mode processes that require FCB processing by INITIALIZER. It is optional for TNS processes. input fcb^array WADDR:ref:* is an array of addresses, each of which points to an FCB to be modified by INITIALIZER. This parameter is required for native mode processes that require FCB processing by INITIALIZER.
Guardian Procedure Calls (H-K) • INITIALIZER Procedure 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.
Guardian Procedure Calls (H-K) INTERPRETINTERVAL Procedure INTERPRETINTERVAL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (H-K) INTERPRETINTERVAL Procedure returns either the number of days in the interval of time (0D or greater), or an error indication of -1D if time is negative. input time FIXED:value specifies the 4-word fixed time interval. output hours INT:ref:1 returns the number of hours in the interval of time (0 or greater). output minutes INT:ref:1 returns the number of minutes in the interval of time (0 or greater).
Guardian Procedure Calls (H-K) INTERPRETJULIANDAYNO Procedure 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).
Guardian Procedure Calls (H-K) INTERPRETJULIANDAYNO Procedure output year INT:ref:1 returns the Gregorian year (for example, 1984, 1985, and so forth). output month INT:ref:1 returns the Gregorian month (1-12). output day 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, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (H-K) INTERPRETTIMESTAMP Procedure INTERPRETTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (H-K) INTERPRETTIMESTAMP Procedure output date-and-time INT:ref:8 returns an array containing the date and time of day. A value of -1 is returned in word [0] if the supplied Julian timestamp is out of range (see “Considerations”).
JULIANTIMESTAMP Procedure Guardian Procedure Calls (H-K) JULIANTIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (H-K) JULIANTIMESTAMP Procedure If type = 3, the value returned is the number of microseconds since the last system load. To convert this retval to a more usable form, use the INTERPRETINTERVAL procedure. input type INT:value is one of the following values specifying the type of time requested: 0 1 2 3 Current GMT System-load GMT SYSGEN GMT Microseconds since system load If type is not supplied, then type 0 is used.
Guardian Procedure Calls (H-K) JULIANTIMESTAMP Procedure Procedures that work with a 64-bit Julian timestamp are COMPUTETIMESTAMP, CONVERTTIMESTAMP, INTERPRETTIMESTAMP, JULIANTIMESTAMP, and SETSYSTEMCLOCK. Where possible, it is recommended that applications use these procedures rather than the procedures that work with 48-bit timestamps. • A 48-bit timestamp is a quantity equal to the number of 10-millisecond units since 00:00, 31 December 1974.
Guardian Procedure Calls (H-K) JULIANTIMESTAMP Procedure Related Programming Manual For programming information about the JULIANTIMESTAMP procedure, refer to the Guardian Programmer’s Guide.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Guardian Procedure Calls (H-K) 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 The KEYPOSITION[X] procedures are used to position by primary or alternate key within a structured file.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Guardian Procedure Calls (H-K) Syntax for TAL Programmers CALL KEYPOSITION[X] ( filenum ,key-value ,[ key-specifier ] ,[ length-word ] ,[ positioning-mode ] ); ! ! ! ! ! i i i i i Parameters input filenum INT:value is the number of an open file where the positioning is to take place. input key-value STRING:ref:* STRING .
Guardian Procedure Calls (H-K) KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) input length-word INT:value contains two values: • • • • • <0:7> compare-length (left byte) specifies, in bytes, the length to use for key comparisons made to decide when to stop returning records under the generic or exact positioning modes. <8:15> key-length (right byte) specifies how many bytes of the key-value are to be searched for in the file to find the initial position.
Guardian Procedure Calls (H-K) KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) matching the key criteria. If positioning-mode.<1> = 0, this bit is ignored. <14:15> indicates the type of key search to perform and the subset of records obtained. 0 approximate Positioning occurs to the first record whose key field, as designated by the key-specifier, contains a value equal to or greater than key-value for key-length bytes (equal to or less than when read-reverse is used).
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Guardian Procedure Calls (H-K) No searching of indexes is done by KEYPOSITION; therefore, a nonexistent or duplicate record is not reported until a subsequent READ, READUPDATE, WRITEUPDATE, LOCKREC, READLOCK, READUPDATELOCK, or WRITEUPDATEUNLOCK is performed.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Guardian Procedure Calls (H-K) 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.
KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) Guardian Procedure Calls (H-K) Record Number Key Value 2 ABB 3 ABC 4 ACA Following an approximate KEYPOSITION to key-value = “AB”, key-length = 2, and positioning-mode = read-reverse, a call to READ would return record number 1 from the set of records shown above. The same call to KEYPOSITION, but with position-to-last also specified, would result in record number 3 being returned from READ.
Guardian Procedure Calls (H-K) KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) When saving the current position in a relative or entry-sequenced file with no alternate keys, the SAVEPOSITION procedure requires an additional three words in the positioning buffer, for a total of seven words when read-reverse positioning is in effect. If you have programs currently using SAVEPOSITION with a four-word positioning buffer, please note this change.
Guardian Procedure Calls (H-K) • • KEYPOSITION[X] Procedures (Superseded by FILE_SETKEY_ Procedure) the address of the key-value parameter is extended, but it is an absolute address and the caller is not privileged. Queue Files To read a queue file in last-in, first-out order, set positioning-mode <0:2> := 3. There are no alternate keys for queue files; the key-specifier parameter must be 0 or omitted.
8 Guardian Procedure Calls (L) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter L. Table 8-1 lists all the procedures in this section. Table 8-1.
Guardian Procedure Calls (L) LABELEDTAPESUPPORT Procedure LABELEDTAPESUPPORT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary This procedure is callable; it provides a way for nonprivileged programs to determine if tape label processing is enabled in the system.
Guardian Procedure Calls (L) LASTADDR Procedure (Superseded by ADDRESS_DELIMIT_ Procedure ) LASTADDR Procedure (Superseded by ADDRESS_DELIMIT_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. LASTADDR (last address) returns the ‘G’[0] relative address of the last word in the application process’s data area.
Guardian Procedure Calls (L) LASTADDRX Procedure (Superseded by ADDRESS_DELIMIT_ Procedure ) LASTADDRX Procedure (Superseded by ADDRESS_DELIMIT_ Procedure ) Summary Syntax for C Programmers CEXTDECS (via 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. Parameters Example Summary Note. This procedure cannot be called by native processes.
Guardian Procedure Calls (L) LASTADDRX Procedure (Superseded by ADDRESS_DELIMIT_ Procedure ) returns 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. input seg INT:value specifies the relative segment number of the segment of interest.
Guardian Procedure Calls (L) LASTRECEIVE Procedure (Superseded by FILE_GETRECEIVEINFO_ LASTRECEIVE Procedure (Superseded by FILE_GETRECEIVEINFO_ 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.
LASTRECEIVE Procedure (Superseded by FILE_GETRECEIVEINFO_ Guardian Procedure Calls (L) Parameters output process-id INT:ref:4 returns the 4-word process ID of the process that sent the last message read through the $RECEIVE file. If the process ID is of the named form and thus in the destination control table (DCT), the information returned consists of: [0:2] [3].<0:3> .<4:7> .
Guardian Procedure Calls (L) LASTRECEIVE Procedure (Superseded by FILE_GETRECEIVEINFO_ Condition Code Settings < (CCL) indicates that $RECEIVE is not open. = (CCE) indicates that LASTRECEIVE was successful. > (CCG) does not return from LASTRECEIVE.
Guardian Procedure Calls (L) LOCATESYSTEM Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure ) LOCATESYSTEM Procedure (Superseded by NODENAME_TO_NODENUMBER_ 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.
Guardian Procedure Calls (L) LOCATESYSTEM Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure ) 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. input, output sysnum INT:ref:1 is the number of the system to be located unless you specify sysname.
LOCKFILE Procedure Guardian Procedure Calls (L) 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).
LOCKFILE Procedure Guardian Procedure Calls (L) Syntax for TAL Programmers CALL LOCKFILE ( filenum ,[ tag ] ); ! i ! i Parameters input filenum INT:value is the number of an open file that identifies the file to be locked. input tag 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.
LOCKFILE Procedure Guardian Procedure Calls (L) • Alternate mode If the file is already locked by another user when the call to LOCKFILE is made, the lock request is rejected, and the call to LOCKFILE completes immediately with error 73 (“file is locked”). The alternate locking mode is specified by calling the SETMODE procedure and specifying function 4. • Locks and open files—applies to non-audited files only Locks are granted on an open file (that is, file number) basis.
Guardian Procedure Calls (L) LOCKFILE Procedure OSS Considerations This procedure operates only on Guardian objects. If an OSS file is specified, error 2 occurs. Related Programming Manual For programming information about the LOCKFILE file-procedure, refer to the Enscribe Programmer’s Guide and the Guardian Programmer’s Guide.
Guardian Procedure Calls (L) LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ 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. LOCKINFO provides information about locks (held or pending) on a local DP2 disk volume.
LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) Guardian Procedure Calls (L) input searchtype INT:value indicates the type of lock search that is desired (see the searchid parameter for more details on search options). Valid values and their uses are: 0 Return lock information for volume searchid. A valid DP2 disk volume name must be placed in searchid[0:3]. Successive calls will eventually return information for all locks on that volume. 1 Return lock information for file searchid.
LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) Guardian Procedure Calls (L) must be passed to LOCKINFO as previously returned. If it is modified in any way, error 41 may be returned. On output, ctlwds returns the information LOCKINFO needs for the next call. These four words must be passed exactly as they were returned on the previous call to LOCKINFO. input buffersize INT:value indicates the size, in bytes, of the buffer available for returned lock information.
LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) Guardian Procedure Calls (L) ! (if LOCKLEN = 0) END; Definitions for the MISC word of the LIB structure (the remaining bits are reserved for future use): DEFINE GENERIC^LOCK = MISC.<0>#; ! If set, record lock is a ! generic key lock The number of LABINFO entries that can be returned to the caller of LOCKINFO depends on the size of the LIB buffer (specified in the parameter buffersize).
Guardian Procedure Calls (L) LOCKINFO Procedure (Superseded by FILE_GETLOCKINFO_ Procedure ) 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.
Guardian Procedure Calls (L) LOCKREC Procedure 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 Procedure Guardian Procedure Calls (L) Syntax for C Programmers #include _cc_status LOCKREC ( short filenum ,[ __int32_t tag ] ); • • CEXTDECS (via 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.
LOCKREC Procedure Guardian Procedure Calls (L) If the LOCKREC procedure is used to initiate an operation with a file opened nowait, it must complete with a corresponding call to the AWAITIO procedure. • Default locking mode If the record is already locked by another user when LOCKREC is called, the process requesting the lock is suspended and queued in a “locking” queue behind other users also requesting to lock or read the record.
LOCKREC Procedure Guardian Procedure Calls (L) ! current record is not ! locked. • Structured files • Calling LOCKREC after positioning on a nonunique key If the call to LOCKREC immediately follows a call to KEYPOSITION where a nonunique alternate key is specified, the LOCKREC fails. A subsequent call to FILE_GETINFO_ or FILEINFO shows that an error 46 (invalid key) occurred. However, if an intermediate call to READ is performed, the call to LOCKREC is permitted because a unique record is identified.
LONGJMP_ Procedure Guardian Procedure Calls (L) 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
Guardian Procedure Calls (L) LONGJMP_ Procedure Considerations • • LONGJMP_ is the TAL or pTAL procedure name for the C longjmp() function. The C longjmp() function complies with the POSIX.1 standard. Do not call LONGJMP_ with a jump buffer that contains the signal mask that was set up by a call to the SIGSETJMP_ procedure, or the system will raise a SIGABRT signal.
Guardian Procedure Calls (L) LONGJMP_ Procedure Related Programming Manual For programming information about the LONGJMP_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (L) LOOKUPPROCESSNAME Procedure (Superseded by PROCESS_GETPAIRINFO_ 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.
LOOKUPPROCESSNAME Procedure (Superseded by PROCESS_GETPAIRINFO_ Guardian Procedure Calls (L) On return, ppd is of the form: Process name of entry [0:2] [3].<0:7> processor for primary process .<8:15> PIN for primary process [4].<0:7> processor of backup process, else 0 .<8:15> PIN of backup process, else 0 process-id of the ancestor. Note that the processid is a 4-word array where process-id[0:2] contains the process name or creation timestamp and processid[3] contains: [5:8] [3].<0:3> .
Guardian Procedure Calls (L) LOOKUPPROCESSNAME Procedure (Superseded by PROCESS_GETPAIRINFO_ To obtain DCT entries using an entry-num, use the GETPPDENTRY procedure. If you call LOOKUPPROCESSNAME for a named process pair whose ancestor is a named process on a remote node with a process name of six characters (including the $), ppd [5:8] is returned filled with zeros.
9 Guardian Procedure Calls (M) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter M. Table 9-1 lists all the procedures in this section. Table 9-1.
Guardian Procedure Calls (M) MBCS_ANY_KATAKANA_ Procedure MBCS_ANY_KATAKANA_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MBCS_ANY_KATAKANA_ procedure checks a string of HP Kanji characters for any Katakana characters. Katakana 1-byte characters are permitted in a string of HP Kanji characters.
Guardian Procedure Calls (M) MBCS_ANY_KATAKANA_ Procedure input length INT:value is the number of bytes in the buffer string. The MBCS_ANY_KATAKANA_ procedure tests only the number of bytes specified in the length parameter and does not access the area beyond buffer[length - 1]. input charset INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the default MBCS character set identifier returned from the MBCS_DEFAULTCHARSET_ procedure is used.
Guardian Procedure Calls (M) MBCS_CHAR_ Procedure MBCS_CHAR_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
MBCS_CHAR_ Procedure Guardian Procedure Calls (M) nonzero indicates that the character set is a supported MBCS, and testmbcschar points to the first byte of a valid character of charset MBCS. For 2-byte character sets, the returned value is the integer value of the sixteen bits which form the multibyte character, using byte-1 as the high order byte and byte-2 as the low order byte of the pair. All currently supported MBCSs are 2-byte character sets. input testmbcschar STRING .
MBCS_CHAR_ Procedure Guardian Procedure Calls (M) <8:15> contains the internal size (in bytes) of the multibyte character identified by the test.
Guardian Procedure Calls (M) MBCS_CHAR_ Procedure THEN -- found valid MBCS character BEGIN -- process and advance pointer ... user-required MBCS character processing here ... @testmbcschar := @testmbcschar + $dbl(charsize.<8:15>); END -- process and advance pointer ELSE -- found a 1-byte character BEGIN -- process and advance pointer ... user-required 1-byte character processing here ...
MBCS_CHARSIZE_ Procedure Guardian Procedure Calls (M) MBCS_CHARSIZE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (M) MBCS_CHARSIZE_ Procedure input charset INT:value identifies the multibyte character set (MBCS) to be used. If charset is omitted or null, the default MBCS identifier returned from the MBCS_DEFAULTCHARSET_ is used.
Guardian Procedure Calls (M) MBCS_CHARSTRING_ Procedure MBCS_CHARSTRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (M) MBCS_CHARSTRING_ Procedure 0 indicates that the charset parameter contains an unknown MBCS identifier (see charinfo description) or contains a known MBCS identifier but the test of testmbcsstring for valid characters failed. 1 indicates that all MBCS characters in the testmbcsstring are valid characters (or blanks) of the specified MBCS. input testmbcsstring STRING .EXT:ref:* is an extended pointer to the first byte of a data string to be tested.
Guardian Procedure Calls (M) MBCS_CHARSTRING_ Procedure Considerations The MBCS_CHARSTRING_ procedure uses the MBCS_CHAR_ procedure to test the specified text string for multibyte characters. All MBCSs supported by the MBCS_CHAR_ procedure are inherently supported by the MBCS_CHARSTRING_ procedure.
Guardian Procedure Calls (M) MBCS_CODESETS_SUPPORTED_ Procedure MBCS_CODESETS_SUPPORTED_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
Guardian Procedure Calls (M) MBCS_CODESETS_SUPPORTED_ Procedure <11> = Chinese PC (5550C) <12> = HP KSC5601 (with KIPS extensions) Other bits are unassigned. Related Programming Manual For programming information about the MBCS_CODESETS_SUPPORTED_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (M) MBCS_DEFAULTCHARSET_ Procedure MBCS_DEFAULTCHARSET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (M) 0 1 9 10 11 12 = = = = = = MBCS_DEFAULTCHARSET_ Procedure No MBCS configured HP Kanji HP Hangul HP Chinese Big 5 HP Chinese PC HP KSC5601 Considerations HP Kanji is the default character set. This default can only be changed by reconfiguring the system. Contact your HP representative for information on changing the default MBCS. Related Programming Manual For programming information about the MBCS_DEFAULTCHARSET_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (M) MBCS_EXTERNAL_TO_TANDEM_Procedure MBCS_EXTERNAL_TO_TANDEM_Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MBCS_EXTERNAL_TO_TANDEM_procedure translates a text string from a specified external format to the HP internal text format. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (M) MBCS_EXTERNAL_TO_TANDEM_Procedure Parameters returned value error-code INT returns a procedure error code. Possible error codes are: 0 -1 -2 -3 -4 -5 29 Successful completion of the translation Translation truncated due to lack of destination buffer space Unknown translation requested Invalid source string length Invalid character in Kanji-only source string Control string parameter too long Required parameter missing source-string input, output INT(32) .
Guardian Procedure Calls (M) MBCS_EXTERNAL_TO_TANDEM_Procedure intermediate input INT:value is a logical flag indicating the optional forms of the source data string. For translations from an EBCDIC type of data format, this parameter is interpreted as follows: When TRUE, the source text string is in an intermediate form which must be further processed to yield the correct ASCII/JIS format for one-byte characters.
MBCS_EXTERNAL_TO_TANDEM_Procedure Guardian Procedure Calls (M) • • 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) output finished-length INT .EXT:ref:1 contains the byte count of the translated destination string upon successful completion of the translation. For other cases, the value is undefined.
MBCS_EXTERNAL_TO_TANDEM_Procedure Guardian Procedure Calls (M) 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] input shift-to-one-byte STRING .EXT:ref:* is an optional pointer to a string containing the escape or control string used to indicate a shift to a 1-byte character set in the source text string.
Guardian Procedure Calls (M) MBCS_EXTERNAL_TO_TANDEM_Procedure Considerations • • • • All parameters except shift-to-MBCS and shift-to-one-byte are necessary for a string translation operation. If any of the optional formal parameters are omitted, the procedure returns, in maximum-length, the maximum possible length in bytes for the destination data buffer. In general, translations to external text formats yield text strings of increased length.
Guardian Procedure Calls (M) MBCS_FORMAT_CRT_FIELD_ Procedure MBCS_FORMAT_CRT_FIELD_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration Summary The MBCS_FORMAT_CRT_FIELD_ procedure formats Kanji only or mixed data types for specific terminal types. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (M) MBCS_FORMAT_CRT_FIELD_ Procedure Syntax for TAL Programmers error-code := MBCS_FORMAT_CRT_FIELD_ ( source-string ,destination-string ,source-length ,maximum-length ,intermediate ,terminal-type ,last-column, ,max-data-size ,screen-start-col ,[ shift-to-MBCS ] ,[ shift-to-one-byte ] ,[ startmode ] ); ! ! ! ! ! ! ! ! ! ! ! ! i,o i,o i i i i i i,o i,o i i i Parameters returned value error-code INT returns a procedure error code.
Guardian Procedure Calls (M) MBCS_FORMAT_CRT_FIELD_ Procedure input source-length INT:value is the length, in bytes, of the source text string. input maximum-length INT: value is the maximum allowable number of bytes of space usable in the output destination string. input intermediate INT:value is a logical flag indicating the desired format of the translated data string. When TRUE, the translated destination CRT field is in pre-EBCDIC format.
Guardian Procedure Calls (M) MBCS_FORMAT_CRT_FIELD_ Procedure 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-startcol and the displayable length of the data inserted into the field by the translate function. shift-to-MBCS input STRING .
Guardian Procedure Calls (M) MBCS_FORMAT_ITI_BUFFER_ Procedure MBCS_FORMAT_ITI_BUFFER_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration 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. Syntax for C Programmers Note.
Guardian Procedure Calls (M) MBCS_FORMAT_ITI_BUFFER_ Procedure #include short MBCS_FORMAT_ITI_BUFFER_ ( __int32_t *source-string ,__int32_t *destination-string ,short source-length ,short maximum-length ,short intermediate ,short terminal-type ,short maximum-col-count ,short *finished-length ,short *screen-col-count ,[ char *shift-to-MBCS ] ,[ char *shift-to-one-byte ] ,[ short startmode ] ); Syntax for TAL Programmers error-code := MBCS_FORMAT_ITI_BUFFER_ ( source-str
Guardian Procedure Calls (M) MBCS_FORMAT_ITI_BUFFER_ Procedure 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.
MBCS_FORMAT_ITI_BUFFER_ Procedure Guardian Procedure Calls (M) input maximum-col-count INT:value indicates the width (in columns) of the display device. output finished-length INT .EXT:ref:1 contains the byte count of the part of the destination string containing successfully translated data. output screen-col-count INT .EXT:ref:1 contains the displayable column count of the formatted buffer. input shift-to-MBCS STRING .
Guardian Procedure Calls (M) MBCS_FORMAT_ITI_BUFFER_ Procedure specifies the optional start mode of the formatting operation. When this parameter has a value of 1, the formatting operation begins in the 1-byte mode. When this parameter has a value of 2, the formatting operation begins in the 2-byte (MBCS) mode. If any other value is specified, or if this parameter is not used, the starting mode is determined from the source string content.
MBCS_MB_TO_SB_ Procedure Guardian Procedure Calls (M) MBCS_MB_TO_SB_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary This procedure and the companion MBCS_SB_TO_MB_ procedure allow conversion of the ninety-four displayable characters of the ASCII character set between 1-byte ASCII and characters of the specified MBCS. The MBCS_MB_TO_SB_ procedure converts multibyte characters to the corresponding 1-byte ASCII characters.
Guardian Procedure Calls (M) MBCS_MB_TO_SB_ Procedure sbytestring:sbytecount output:input STRING .EXT:*, INT:value returns the converted text string containing 1-byte characters. The string variable sbytestring must be exactly sbytecount bytes long. output rbytecount INT .EXT:ref:1 returns the actual byte length of the converted text string contained in sbytestring. input charset INT:value is the optional identifier of the reference MBCS.
MBCS_REPLACEBLANK_ Procedure Guardian Procedure Calls (M) MBCS_REPLACEBLANK_ Procedure Summary Syntax for C Programmers Sytax 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.
MBCS_REPLACEBLANK_ Procedure Guardian Procedure Calls (M) is a pointer to a buffer containing a properly formed text string that may contain any mixture of 1-byte and MBCS characters. A properly formed text string may not begin with the second or subsequent byte of an MBCS character or end with any byte of a MBCS character other than the last. (See the MBCS_TRIMFRAGMENT_ procedure.) The contents of the bytestring pointer are not altered by the shift operation.
Guardian Procedure Calls (M) MBCS_REPLACEBLANK_ Procedure character sets contain embedded blanks. When using any of the supported MBCSs other than HP Hangul, following the use of this procedure, any remaining bytes having the value of %H20 can be interpreted as ordinary blanks. When the HP Hangul character set is specified, extra care is required because byte values of %H20 can appear as 1-byte blanks, the second byte of multibyte characters, or in pairs as 2-byte blanks.
Guardian Procedure Calls (M) MBCS_SB_TO_MB_ Procedure MBCS_SB_TO_MB_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary This 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 1-byte ASCII and characters of the specified MBCS. The MBCS_SB_TO_MB_ procedure converts 1-byte ASCII characters to the corresponding multibyte characters.
Guardian Procedure Calls (M) MBCS_SB_TO_MB_ Procedure mbytestring:mbytecount output:input STRING .EXT:*, INT:value returns the converted text string containing multibyte characters. The string variable mbytestring must be exactly mbytecount bytes long. output rbytecount INT .EXT:ref:1 returns the actual byte length of the converted text string contained in mbytestring. input charset INT:value is the optional identifier of the reference MBCS.
Guardian Procedure Calls (M) MBCS_SHIFTSTRING_ Procedure MBCS_SHIFTSTRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration 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 1-byte alphabetic characters of the ASCII character set are case shifted by this procedure.
Guardian Procedure Calls (M) MBCS_SHIFTSTRING_ Procedure input bytecount INT:value is an integer variable containing the length in bytes of the text string bytestring. input casebit INT:value is a variable indicating the type of case shift to be applied to the 1-byte alphabetic characters in the bytestring. When the case bit (bit <15>) is set to 0, an upshift is requested; when the case bit is set to 1, a downshift is requested.
Guardian Procedure Calls (M) MBCS_TANDEM_TO_EXTERNAL_ Procedure MBCS_TANDEM_TO_EXTERNAL_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MBCS_TANDEM_TO_EXTERNAL_ procedure translates a text string from HP internal format to a specified external text format. Syntax for C Programmers Note: In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (M) MBCS_TANDEM_TO_EXTERNAL_ Procedure Syntax for TAL Programmers error-code := MBCS_TANDEM_TO_EXTERNAL_ ( source-string ,destination-string ,source-length ,maximum-length ,intermediate ,external-form ,finished-length ,[ shift-to-MBCS ] ,[ shift-to-one-byte ] ); ! ! ! ! ! ! ! ! ! i,o i,o i i,o i i o i i Parameters returned value error-code INT returns a procedure error code.
Guardian Procedure Calls (M) MBCS_TANDEM_TO_EXTERNAL_ Procedure input source-length 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. When the source-length, maximum-length, and external-form parameters are supplied but other parameters are missing, maximum-length returns the maximum length required for a destination string.
Guardian Procedure Calls (M) MBCS_TANDEM_TO_EXTERNAL_ Procedure The twelve low-order bits of this parameter (external-form.
MBCS_TANDEM_TO_EXTERNAL_ Procedure Guardian Procedure Calls (M) provided. The IBM Kanji character attribute (described following) is an example of an alternative format. The alternative format must be expressed as (null flag, count, string), where the first byte is a null flag indicator of the alternative string form, the second byte contains an integer value representing the length of the control string, and the third and subsequent bytes represent the value of the control string.
MBCS_TANDEM_TO_EXTERNAL_ Procedure Guardian Procedure Calls (M) input shift-to-one-byte STRING .EXT:ref:* is an optional pointer to a string containing the escape or control string used to indicate a shift to a 1-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.
MBCS_TANDEM_TO_EXTERNAL_ Procedure Guardian Procedure Calls (M) • In the HP internal character sets, text bytes having the byte value x20 are used to represent blank characters or spaces in both the 1-byte and the 2-byte character sets. A 1-byte blank is represented by a single x20 byte. A 2-byte blank is represented by two consecutive x20 bytes.
MBCS_TANDEM_TO_EXTERNAL_ Procedure Guardian Procedure Calls (M) • • When MBCS_TANDEM_TO_EXTERNAL_ finds invalid or nondisplayable two-byte characters in the source string, it maps them to reserved values as follows: Destination Format Invalid Pairs Map to Nondisplayable Pairs Map to IBM %HFEFE %HFEFD Fujitsu %HA0FE %HA0FD JIS %H2222 %H2223 The definition of nondisplayable and illegal characters varies with the target mapping format.
Guardian Procedure Calls (M) MBCS_TESTBYTE_ Procedure MBCS_TESTBYTE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The MBCS_TESTBYTE_ procedure returns the identification of a specified byte contained within a text string of mixed data.
Guardian Procedure Calls (M) MBCS_TESTBYTE_ Procedure input buffer STRING .EXT:ref:* is a pointer to a buffer containing a properly formed text string which may contain any mixture of 1-byte and multibyte characters. A properly formed text string may not begin with the second or subsequent byte of a multibyte character or end with a fragment of a multibyte character. The buffer is not altered by the test operation. This procedure does not alter the contents of the text string referenced by buffer.
Guardian Procedure Calls (M) MBCS_TESTBYTE_ Procedure Considerations • A simple range check is not adequate to establish positive identification of MBCS byte usages. The set of second-byte values used by Shift-JIS Kanji characters overlaps the byte value ranges of ASCII, 1-byte Katakana, and the set of byte values used for the first byte of Shift-JIS Kanji characters.
MBCS_TRIMFRAGMENT_ Procedure Guardian Procedure Calls (M) 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.
Guardian Procedure Calls (M) MBCS_TRIMFRAGMENT_ Procedure Parameters input bytestring STRING .EXT:ref:* is a pointer to a buffer containing a text string which may contain any mixture of 1byte and MBCS characters. The content of the bytestring pointer is not altered by the trim operation. input, output bytecount INT .EXT:ref:1 on input, is an integer variable containing the length in bytes of the text string bytestring.
Guardian Procedure Calls (M) MESSAGESTATUS Procedure MESSAGESTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Related Programming Manual Summary MESSAGESTATUS determines if a particular message received through READUPDATE has been canceled.
Guardian Procedure Calls (M) MESSAGESTATUS Procedure certain forms of AWAITIO; cancellation will also be caused by a stop of the originating process, failure of the originator’s processor, or a network communication failure. • This procedure is best used for a program that is concerned about one particular request. If a program deals with many requests concurrently and constantly monitors $RECEIVE, use of system message -38 (queued message cancellation) may be more appropriate.
Guardian Procedure Calls (M) MESSAGESYSTEMINFO Procedure MESSAGESYSTEMINFO Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary MESSAGESYSTEMINFO 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.
Guardian Procedure Calls (M) MESSAGESYSTEMINFO Procedure input itemcode INT:value specifies the item code of the information to be retrieved. See the following list. output value INT .EXT:ref:1 returns the value indicated in the following list. Item Code Returned Value 0 Current limit on the number of messages to this process, as set by CONTROLMESSAGESYSTEM. 1 Current limit on the number of messages from this process, as set by CONTROLMESSAGESYSTEM.
MOM Procedure (Superseded by PROCESS_GETINFOLIST_ Guardian Procedure Calls (M) MOM Procedure (Superseded by PROCESS_GETINFOLIST_ 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 MOM procedure provides a process with the 4-word process ID of its creator.
MOM Procedure (Superseded by PROCESS_GETINFOLIST_ Guardian Procedure Calls (M) .<8:15> PIN assigned by the operating system to identify the process in the processor For a named local process, process-id is: [0:2] [3].<0:3> .<4:7> .<8:15> $process-name Reserved processor number where the process is executing PIN assigned by the operating system to identify the process in the processor For a named remote process, process-id is: [0].<0:7> .<8:15> [1:2] [3].<0:3> .<4:7> .
Guardian Procedure Calls (M) • MOM Procedure (Superseded by PROCESS_GETINFOLIST_ Calling MOM from a high-PIN process If the mom of the calling process is a high-PIN process, MOM returns a synthetic process ID. A synthetic process ID contains a PIN value of 255 in place of a highPIN value, which cannot be represented by 8 bits.
MONITORCPUS Procedure Guardian Procedure Calls (M) MONITORCPUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 applicatio
Guardian Procedure Calls (M) MONITORCPUS Procedure Messages • processor down System message -2 (processor down) is received if failure occurs with a processor module that is being monitored (refer to the Guardian Procedure Errors and Messages Manual for the description and form of system messages). Please be aware that this message expires in 3 minutes; it must be read before expiration or it will be lost.
MONITORNET Procedure Guardian Procedure Calls (M) MONITORNET Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The MONITORNET procedure enables or disables receipt of system messages concerning the status of processors in remote systems.
Guardian Procedure Calls (M) MONITORNET Procedure See the Guardian Procedure Errors and Messages Manual for details on system messages sent to processes.
MONITORNEW Procedure Guardian Procedure Calls (M) MONITORNEW Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration Summary The MONITORNEW procedure enables or disables receipt of the SETTIME and Power On messages.
MOVEX Procedure Guardian Procedure Calls (M) MOVEX Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary MOVEX moves data between extended data segments without the need for absolute addressing; it serves both privileged and nonprivileged users.
Guardian Procedure Calls (M) 24 MOVEX Procedure Either source-seg-id or dest-seg-id specified a privileged segment ID (greater than 2047), but the caller was not privileged. A required parameter is not supplied. 29 source-seg-id input INT:value specifies the segment ID of the extended data segment referenced by source.
MOVEX Procedure Guardian Procedure Calls (M) • • • • • • The currently in-use selectable segment and flat extended data segments nonextended relative locations extended and nonextended relative locations If the caller is privileged, no bounds checking is performed.
Guardian Procedure Calls (M) MYGMOM Procedure (Superseded by PROCESS_GETINFOLIST_ MYGMOM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
Guardian Procedure Calls (M) MYGMOM Procedure (Superseded by PROCESS_GETINFOLIST_ MYGMOM, you can pass the process ID as a file name to any Guardian procedure.) • • If the job ancestor of the calling process is a high-PIN process, MYGMOM returns a synthetic process ID. A synthetic process ID contains a PIN value of 255 in place of a high-PIN value, which cannot be represented by 8 bits.
Guardian Procedure Calls (M) MYPID Procedure (Superseded by PROCESSHANDLE_GETMINE_ Procedure and MYPID Procedure (Superseded by PROCESSHANDLE_GETMINE_ Procedure and PROCESSHANDLE_DECOMPOSE_ 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. The MYPID procedure provides a process with its own processor and PIN number.
Guardian Procedure Calls (M) MYPID Procedure (Superseded by PROCESSHANDLE_GETMINE_ Procedure and Considerations If the caller of the MYPID procedure is a high-PIN process, the call to MYPID fails: a TNS Guardian process terminates with a limits exceeded trap (trap 5); an OSS or native process receives a SIGLIMIT signal.
Guardian Procedure Calls (M) MYPROCESSTIME Procedure MYPROCESSTIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (M) MYSYSTEMNUMBER Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure or 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 Parameters Consideration Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (M) MYSYSTEMNUMBER Procedure (Superseded by NODENAME_TO_NODENUMBER_ Procedure or Consideration • Part of network or local system The following IF (skeleton) statement determines if you are running on a network system. IF NOT ( SYS^NUM := MYSYSTEMNUMBER ) THEN ! not on network system If the caller is running in a local nonnamed system, MYSYSTEMNUMBER returns 0.
Guardian Procedure Calls (M) MYTERM Procedure (Superseded by PROCESS_GETINFOLIST_ MYTERM Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers 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.
Guardian Procedure Calls (M) MYTERM Procedure (Superseded by PROCESS_GETINFOLIST_ NEWPROCESS, NEWPROCESSNOWAIT, OSS tdm_fork(), OSS tdm_spawn(), or one of the OSS tdm_exec set of functions. If the process calling MYTERM is a descendant of a command interpreter, then the home terminal is the same as that of the command interpreter or that of an explicit TERM specifier on the RUN command.
10 Guardian Procedure Calls (N) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter N. Table 10-1 lists all the procedures in this section. Table 10-1.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations Example Related Programming Manual Summary Note.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Syntax for TAL Programmers CALL NEWPROCESS ( filenames ,[ priority ] ,[ memory-pages ] ,[ processor ] ,[ process-id ] ,[ error ] ,[ name ] ,[ hometerm ] ,[ flags ] ,[ jobid ] ,[ errinfo ] ,[ pfs-size ] ); ! ! ! ! ! ! ! ! ! ! ! i i i i o o i i i i o ! i Parameters input filenames INT:ref:12 or INT:ref:36 is an array that contains the internal-format file name of the program to be run and, optionally, two addit
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Kernel-Managed Swap Facility (KMSF) Manual. To reserve swap space for the process, create the process using the PROCESS_LAUNCH_ procedure and specify the Z^SPACE^GUARANTEE field of the param-list parameter. Alternatively, use the nld utility to set native process attributes.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) input processor INT:value specifies the processor where the new process runs. If omitted, the new process runs in the same processor as the caller. output process-id INT:ref:4 is a four-word array where NEWPROCESS returns the process ID of the new process. If the new process was created in: • • The local system, then the local form of the process ID is returned.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) process-name must be preceded by a dollar sign (“$”) and consists of a maximum of five alphanumeric characters; the first character must be alphabetic. (If the process is created on a remote system and it is necessary to be able to access the process, its name should consist of, at most, four characters and the “$”; this leaves a byte for the system to insert the node number.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) input jobid INT:value is an integer identifying a new job to be created with the new process as the first process of the job and the caller as the GMOM of the new process. This integer is used by the NetBatch Scheduler. (See “Batch Processing Considerations.”) output errinfo INT .
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 2 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 3 File-system error occurred on program file: <8:15> is file-system error number* 4 Unable to allocate map 5 File-system error occurred on swap file: <8:15> is a file-system error number* 6 Illegal file format: 2 Program file is not a disk file.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 3 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 6, continued 22 The file was not prepared by the nld utility or the Binder program. 23 Library file was not prepared by the nld utility or the Binder program. 24 Program file has undefined data blocks. 25 Library file has undefined data blocks.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 4 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 6, continued 46 Program file has entry in native fixup list with invalid external entry point (XEP) index value or invalid code address value.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 5 of 12) error <0 : 7> 6, continued Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 62 An internal structure of the program file contains an error. 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.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 6 of 12) error <0 : 7> 6, continued Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 80 The code in the program file starts at the wrong virtual address. 81 The code in the library file starts at the wrong virtual address. 82 The program file has too much data for the main stack.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 7 of 12) error <0 : 7> 6, continued Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 97 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.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 8 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 110 The program file is not executable because it does not have either a HP information header, a REGINFO information header, or a text header. An error occurred during the linking of the program file.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 9 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> <8:15> 15 Invalid home terminal: <8:15> 16 is a file-system error number*. I/O error to home terminal: <8:15> 17 is a file-system error number*. is a file-system error number*.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 11 of 12) error <0 : 7> Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 43 Program file requires a symbol from a shared run-time library (SRL) but the SRL is not exporting it; error.
NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Table 10-2. Summary of NEWPROCESS Error Codes (page 12 of 12) error <0 : 7> 5xx Corresponding Process Creation Error (see Table 12-4 on page 12-127) <8:15> 11 The shared run-time library (SRL) was not prepared by nld utility. 40 The shared run-time library (SRL) code starts at the wrong virtual address, has invalid text, or invalid data. 42 The shared run-time library (SRL) code area is too large.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) If library-file: • • • is specified, unresolved external references are resolved first from the specified library-file, then from the system library. is specified and library-file[0] is 0 (binary), then the library file used by the process when it was last run is removed, and the process runs with no library file.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) used with PIC programs). Refer to the ld and rld Reference Manual for more information about dynamic-link libraries (including native user libraries used with PIC programs) • Library conflict—NEWPROCESS error The library file for a process can be shared by any number of processes.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) The creator access ID of the new process is always the same as the process access ID of the creator process. The process access ID of the new process is the same as that of the creator process unless the program file has the PROGID attribute set; in that case the process access 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.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) 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 sends a job process creation message to the job ancestor of the batch job.
Guardian Procedure Calls (N) NEWPROCESS Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) OSS Considerations • • • You cannot create an OSS process using the NEWPROCESS procedure. NEWPROCESS returns error 12 if you try. You can call NEWPROCESS from an OSS process to create a Guardian process. Every Guardian process has the following security-related attributes for accessing OSS objects.
Guardian Procedure Calls (N) NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations NEWPROCESSNOWAIT Completion Message DEFINE Considerations Batch Processing Considerations OSS Considerations Example Related Programming Manual Summary Note.
Guardian Procedure Calls (N) NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Syntax for TAL Programmers CALL NEWPROCESSNOWAIT ( filenames ,[ priority ] ,[ memory-pages ] ,[ processor ] ,[ process-id ] ,[ outcome ] ,[ name ] ,[ hometerm ] ,[ flags ] ,[ jobid ] ,[ errinfo ] ,[ pfs-size ] ); ! ! ! ! ! ! ! ! ! ! ! ! i i i i unused o i i i i o i Parameters input filenames INT:ref:12 or INT:ref:38 is an array that contains the internal-format file name of the program to be run and thr
Guardian Procedure Calls (N) NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Managed Swap Facility (KMSF) Manual. To reserve swap space for the process, create the process using the PROCESS_LAUNCH_ procedure and specify the Z^SPACE^GUARANTEE field of the param-list parameter. Alternatively, use the nld utility to set TNS/R native process attributes or the eld utilitiy to set TNS/E native process attributes.
NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) Z^MAINSTACK^MAX, Z^HEAP^MAX, and Z^SPACE^GUARANTEE fields of the param-list parameter. Alternatively, use the nld utility to set the process attributes. input processor INT:value is a value specifying the processor where the new process runs. If omitted, the new process runs in the same processor as the caller.
NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (N) cpu,pin of the new process in the fourth word. The process-name will not be entered into the DCT. input hometerm INT:ref:12 is the internal-format file name of the home terminal for the new process. The specified value must designate a terminal or a process. The default is the home terminal of the caller. input flags INT:value flags.<10:12> are used to supply the DEFINE mode for the new process: flags.
Guardian Procedure Calls (N) NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) errinfo[0] error errinfo[1] error-detail (provides additional information about the error) Table 10-2 on page 10-7 summarizes the error values and relates them to process creation errors (as issued by PROCESS_LAUNCH_) described in Table 12-4 on page 12-127. input pfs-size INT(32):value meaningful only if the process is being created on a pre-G06 RVU.
Guardian Procedure Calls (N) • • • NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) is not specified, a =_DEFAULTS DEFINE swap-file is used if available, otherwise a temporary file is created on the disk where the program file resides. specifies only the device name (filling the rest of the file name with blanks), a temporary file is created on the specified device.
Guardian Procedure Calls (N) • • NEWPROCESSNOWAIT Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) You can call NEWPROCESSNOWAIT from an OSS process to create a Guardian process. Every Guardian process has the following security-related attributes for accessing OSS objects.
Guardian Procedure Calls (N) NEXTFILENAME Procedure (Superseded by FILENAME_FINDNEXT_ NEXTFILENAME Procedure (Superseded by FILENAME_FINDNEXT_ 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. The NEXTFILENAME procedure is used to obtain the name of the next disk file on a designated volume.
NEXTFILENAME Procedure (Superseded by FILENAME_FINDNEXT_ Guardian Procedure Calls (N) 0 No error; next file name in alphabetic sequence is returned in file-name. 1 End-of-file, there is no file in alphabetic sequence following the file name supplied in file-name. 13 Illegal file name specification. Refer to the Guardian Procedure Errors and Messages Manual for a list of all filesystem errors.
Guardian Procedure Calls (N) NEXTFILENAME Procedure (Superseded by FILENAME_FINDNEXT_ Example FNAME ':=' [ "$SYSTEM ", 8 * [" "]]; WHILE NOT (ERROR := NEXTFILENAME ( FNAME ) ) DO BEGIN . . .
NO^ERROR Procedure Guardian Procedure Calls (N) NO^ERROR Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary NO^ERROR 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.
Guardian Procedure Calls (N) • • • NO^ERROR Procedure Error is a good error number on the list. Fatal error occurred, and abort-on-error mode is OFF. Error is a BREAK error, and BREAK is enabled for file-fcb. input state INT:value if nonzero, indicates the operation is considered successful. The file error and retry count variables in the file control block (FCB) are set to zero, with no-retry returned as nonzero.
Guardian Procedure Calls (N) Device Retry Indication Disk (opened with sync depth of 1, so not applicable) Terminal Yes Printer Yes Mag Tape No NO^ERROR Procedure If the path error is either of {200:201}, a retry indication is given in all cases following the first attempt. Example INT GOOD^ERROR [ 0:1 ] := [ 1, 11 ]; ! nonexistent record. . . .
Guardian Procedure Calls (N) NODE_GETCOLDLOADINFO_ Procedure NODE_GETCOLDLOADINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (N) NODE_GETCOLDLOADINFO_ Procedure filename:maxlen output:input STRING .EXT:ref:*, INT:value returns the fully qualified name of the file from which the specified node was system loaded. maxlen is the length in bytes of the string variable filename. output filename-length INT .EXT:ref:1 is the actual length in bytes of the returned file name. nodename:length input:input STRING .
Guardian Procedure Calls (N) NODENAME_TO_NODENUMBER_ Procedure NODENAME_TO_NODENUMBER_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (N) NODENAME_TO_NODENUMBER_ Procedure specifies the name of the node whose number is to be returned. nodename must be exactly length bytes long. If nodename is omitted or if length is 0, the number of the local node is returned. output nodenumber INT(32) .EXT:ref:1 returns the number of the specified node. If nodename is omitted or if length is 0, nodenumber returns the number of the caller’s node. output ldevnum INT(32) .
Guardian Procedure Calls (N) NODENUMBER_TO_NODENAME_ Procedure NODENUMBER_TO_NODENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration 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.
Guardian Procedure Calls (N) NODENUMBER_TO_NODENAME_ Procedure nodename:maxlen output:input STRING .EXT:ref:*, INT:value returns the name of the specified node. If nodenumber is omitted, nodename returns the name of the caller’s node. maxlen specifies the length in bytes of the string variable nodename. nodename-length output INT .EXT:ref:1 returns the length in bytes of the value returned in nodename. output ldevnum INT(32) .
NSK_FLOAT_IEEE TO TNS Procedures Guardian Procedure Calls (N) 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 These procedures convert numbers in the IEEE floating-point format to numbers in the TNS floating-point format. The specific functions of each are as follows: Procedure Function NSK_FLOAT_IEEE32_TO_TNS32_ Convert a 32-bit IEEE floating-point value to a 32-bit TNS floating-point value.
Guardian Procedure Calls (N) NSK_FLOAT_IEEE32_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS32_ Procedure Syntax for C Programmers #include
NSK_FLOAT_IEEE32_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS32_ Procedure Guardian Procedure Calls (N) The following is a list of the error bits that can be set by at least one of the three IEEE_TO_TNS conversion procedures: NSK_FLOAT_TNS_OVERFLOW The input was out of range (either too big in magnitude, infinity, or not a number (NaN)). The result had the largest possible magnitude. NSK_FLOAT_TNS_UNDERFLOW The input was out of range (too small in magnitude) and could not be represented correctly.
NSK_FLOAT_IEEE32_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS32_ Procedure Guardian Procedure Calls (N) input IEEE_Data INT .ext:ref (NSK_float_ieee32) The 32-bit IEEE floating-point number. output TNS_Data INT .ext:ref (NSK_float_tns64) The 64-bit TNS floating-point number For NSK_FLOAT_IEEE64_TO_TNS64_: input IEEE_Data INT .ext:ref (NSK_float_ieee64) The 64-bit IEEE floating-point number. output TNS_Data INT .
Guardian Procedure Calls (N) NSK_FLOAT_IEEE32_TO_TNS32_ Procedure NSK_FLOAT_IEEE64_TO_TNS32_ Procedure Examples C Example #include #include void example1(void) { NSK_float_ieee64 before; NSK_float_tns32 after; ReadIEEE64(&before); /* read in value to convert */ if( NSK_FLOAT_IEEE64_TO_TNS32_( &before, &after ) & NSK_FLOAT_TNS_OVERFLOW ) printf( "Overflow!\n" ); WriteTNS32(&after); /* write out result */ } TAL Example ?nolist ?source $system.system.
NSK_FLOAT_TNS TO IEEE Procedures Guardian Procedure Calls (N) 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 These procedures convert numbers in the TNS floating-point format to numbers in the IEEE floating-point format. The specific functions of each are as follows: Procedure Function NSK_FLOAT_TNS32_TO_IEEE32_ Convert a 32-bit TNS floating-point value to a 32-bit IEEE floating-point value.
Guardian Procedure Calls (N) NSK_FLOAT_TNS32_TO_IEEE32_ Procedure NSK_FLOAT_TNS32_TO_IEEE64_ Procedure Syntax for C Programmers #include
NSK_FLOAT_TNS32_TO_IEEE32_ Procedure NSK_FLOAT_TNS32_TO_IEEE64_ Procedure Guardian Procedure Calls (N) The following is a list of the error bits that can be set by at least one of the three TNS_TO_IEEE conversion procedures: NSK_FLOAT_IEEE_OVERFLOW The input was out of range (too big in magnitude), and the result was an IEEE infinity. The sign of the result matched the sign of the input.
Guardian Procedure Calls (N) NSK_FLOAT_TNS32_TO_IEEE32_ Procedure NSK_FLOAT_TNS32_TO_IEEE64_ Procedure The 64-bit TNS floating-point number. output IEEE_Data INT .ext:ref NSK_float_ieee64 The 64-bit IEEE floating-point number Considerations See Considerations on page 10-47 for description of considerations for this procedure. Examples C Example #include #include
NUMBEREDIT Procedure Guardian Procedure Calls (N) NUMBEREDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (N) NUMBEREDIT Procedure -6 Exhausted valid line numbers. -10 Unable to complete renumbering; file is unchanged. input filenum INT:value is the number that identifies the open file in which lines are to be renumbered. input first INT(32):value specifies 1000 times the line number of the first line in the range of lines to be renumbered. If a negative value is specified, the line number of the first line in the file is used.
Guardian Procedure Calls (N) NUMBEREDIT Procedure INT(32) increment := 100D; . . err := NUMBEREDIT ( filenumber, first, last, start, increment ); Related Programming Manual For programming information about the NUMBEREDIT procedure, refer to the Guardian Programmer’s Guide.
NUMIN Procedure Guardian Procedure Calls (N) NUMIN Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (N) NUMIN Procedure where “%” means treat the number as a binary, octal, or hexadecimal value (as indicated) regardless of the specified base. Note that nonnumeric applies only to hexadecimal values. signed-result output INT:ref:1 returns the result of the conversion. input base INT:value specifies the number base of ascii-num. Legitimate values are 2 through 10 and 16. output status INT:ref:1 returns a number that indicates the outcome of the conversion.
NUMOUT Procedure Guardian Procedure Calls (N) NUMOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration 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.
Guardian Procedure Calls (N) NUMOUT Procedure input base INT:value is the number base for the resulting conversion. Any number in the range 2 to 10 is valid. input width INT:value is the maximum number of characters permitted in ascii-result. Characters might be truncated on the left side. Consideration If width is too small to contain the number, the most significant digits are lost.
11 Guardian Procedure Calls (O) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter O. Table 11-1 lists all the procedures in this section. Table 11-1.
Guardian Procedure Calls (O) OBJFILE_GETINFOLIST_ Procedure OBJFILE_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers parameters General Consideration Attribute Codes and Value Representations 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.
Guardian Procedure Calls (O) OBJFILE_GETINFOLIST_ Procedure parameters returned value error INT indicates the outcome of the operation. It returns one of the following values: 0 Information is returned successfully. 1 File-system error; error-detail contains the error number. Error 563 (buffer too small) is returned if ret-values-list is too small to contain all the requested information.
Guardian Procedure Calls (O) OBJFILE_GETINFOLIST_ Procedure ret-values-maxlen input INT:value specifies the maximum length in bytes of ret-values-list. The size of retvalues-list cannot exceed 1024 bytes. ret-values-len output INT .EXT:ref:1 returns the actual length in bytes of ret-values-list. input lib-info INT:value specifies whether you are requesting information on an object file or a library file.
OBJFILE_GETINFOLIST_ Procedure Guardian Procedure Calls (O) Attribute Codes and Value Representations The individual attribute codes and their associated value representations are as follows: Attribute Code TAL Value Representation 1 Binder timestamp (for TNS object files only) INT (3 words) 2 minimum tosversion (for TNS object files only) INT 3 Inspect length (for TNS object files only) INT(32) 4 Binder length (for TNS object files only) INT(32) 5 Inspect on INT 6 high PIN INT 7 high
Guardian Procedure Calls (O) OBJFILE_GETINFOLIST_ Procedure is the earliest RVU of the operating system on which the object file can run. For a description of the tosversion, refer to the TOSVERSION procedure. A value of 0 indicates that either the object file can run on any RVU of the operating system or the object file is a native object file. • 3: Inspect length (for TNS object files only) is the length in bytes of the Inspect region of the file.
Guardian Procedure Calls (O) 2 3 OBJFILE_GETINFOLIST_ Procedure TNS processors Any If the object file is a native object file, the value of this attribute is always 1 (TNS/R or TNS/E processors). • 11: accelerator timestamp (for TNS object files only) is the four-word Julian timestamp for when the object file was accelerated. For a description of the Julian timestamp, refer to the JULIANTIMESTAMP procedure. If the file is not accelerated or the file is a native object file, 0 is returned.
OBJFILE_GETINFOLIST_ Procedure Guardian Procedure Calls (O) Returns a null list of SRLs if the file is PIC. Tal Value Representati on Description INT Number of shared run-time library names returned. This value indicates how many pairs of INT and STRING listed, as below. follow this value. INT Length of the shared run-time library name. STRING Name. (The returned string ends on an odd-byte boundary so that the next attribute returned will begin on an even-byte boundary.
Guardian Procedure Calls (O) OLDFILENAME_TO_FILENAME_ Procedure OLDFILENAME_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 Dseries file names.
Guardian Procedure Calls (O) OLDFILENAME_TO_FILENAME_ Procedure filename:maxlen output:input STRING .EXT:ref:*, INT:value contains the resulting file name. maxlen specifies the length in bytes of the string variable filename. filename-length output INT .EXT:ref:1 returns the actual byte length of the file name returned in filename. 0 is returned if an error occurs. Considerations • • • The output file name always includes a node name regardless of whether the input name was in network form.
Guardian Procedure Calls (O) OLDSYSMSG_TO_NEWSYSMSG_ Procedure OLDSYSMSG_TO_NEWSYSMSG_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The OLDSYMSG_TO_NEWSYSMSG_ procedure converts a C-series format system message to its D-series equivalent. See “Considerations” for a list of the messages that this procedure accepts and produces.
Guardian Procedure Calls (O) OLDSYSMSG_TO_NEWSYSMSG_ Procedure 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 The supplied system message is not supported by this procedure; no conversion was performed. input:input oldmsg:length STRING .EXT:ref:*, INT:value is the message to be converted. oldmsg must be exactly length bytes long. output:input newmsg:maxlen STRING .
Guardian Procedure Calls (O) OLDSYSMSG_TO_NEWSYSMSG_ Procedure C-series message D-series message -8 Network status change (single processor down, 0 or more processors up) 100 Remote processor down -8 Network status change (2 or more processors down, 0 or more processors up) 110 Loss of communication with node -8 Network status change (connection established) 111 Establishment of communication with node -8 Network status change (0 or more processors up when node already connected) 113 Remo
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) 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 Consideration Interprocess Communication Considerations Message DEFINE Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary Note.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Parameters input file-name INT:ref:12 is an array containing the internal-format file name of the file to be opened. Refer to Appendix D, File Names and Process Identifiers for additional information about file names. Note that file-name can be a DEFINE name. Refer to Appendix E, DEFINEs for additional information about DEFINEs.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) process pair specifies whether or not an I/O operation is automatically redirected to the backup process if the primary process or its processor module fails. For processes, this parameter is called sync depth. The maximum value is determined by the process. The value must be at least 1 for an I/O operation to a remote process pair to recover from a network failure.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) 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.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Guardian Procedure Calls (O) Condition Code Settings < (CCL) indicates that the open failed (call FILEINFO or FILE_GETINFO_). If OPEN fails, a -1 is returned in filenum.= (CCE)indicates that the file was opened successfully. > (CCG) indicates the file was opened successfully but an exceptional condition was detected (call FILEINFO or FILE_GETINFO_). Table 11-2.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Guardian Procedure Calls (O) Table 11-2. OPEN flags Parameter (page 2 of 2) Flag Flag in Octal Meaning <9> %100 Must be 0 (reserved) <10:11 > %60 (If both bits set) Exclusion mode <12:15 > %17 (If all four bits set) > 0 implies nowait I/O and the maximum number of concurrent nowait I/O operations that can be in progress on this file at any given time.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) ! second open on file MYFILE. . . OPEN( MYFILE , filenumc ... ); ! third open on file MYFILE. . ---d . e LOCKFILE ( filenumb, ... ); a . d . l . o READUPDATE ( filenumc, ... ); c . k . ---- ! ! ! ! ! ! ! the file is locked using the file number associated with the second open. update the file associated with the third open. Locks are granted on an open file (that is, file number) basis.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Guardian Procedure Calls (O) If there are no parameter or data space allocation errors, the filenum parameter is valid when OPEN returns. However, no I/O operation on the file can be initiated until the open is completed, and other errors are reported by a call to AWAITIO. If the tag parameter is specified in the call to AWAITIO, a -30D returns. The values returned in the buffer and count parameters to AWAITIO are undefined.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Guardian Procedure Calls (O) Table 11-3.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) 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.
OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Guardian Procedure Calls (O) Table 11-5 lists the possible current modes and requested modes, indicating whether an open succeeds or fails. Note. Protected exclusion mode has meaning only for disk files. For other files, specifying protected exclusion mode is equivalent to specifying shared exclusion mode. Table 11-5.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) 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.
Guardian Procedure Calls (O) • • OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) The positioning mode is approximate. The comparison length is 0. If READ is called immediately after OPEN for any structured file, it reads the first record in the file; in a key-sequenced file, this is the first record by primary key. Subsequent reads, without intervening positioning, read the file sequentially or by primary key through the last record in the file.
Guardian Procedure Calls (O) • OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Opening high-PIN processes The OPEN procedure cannot be used to open a high-PIN unnamed process because the process ID cannot fit into the process file name; FILE_OPEN_ must be used instead. However the OPEN procedure can be used on high-PIN named processes, devices, and files on high-PIN volumes. • Opening an unconverted (C-series) process from a high-PIN process.
Guardian Procedure Calls (O) OPEN Procedure (Superseded by FILE_OPEN_ Procedure ) Safeguard Considerations For information on files protected by Safeguard, refer to 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 OPEN ( FILE^NAME , FILE^NUM ); The file in this call has the following defaults; wait I/O, exclusion mode (shared), access mode (read/write), sync depth (0).
Guardian Procedure Calls (O) OPEN^FILE Procedure OPEN^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General 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.
Guardian Procedure Calls (O) OPEN^FILE Procedure Parameters returned value error INT returns a file-system or SIO procedure error number indicating the outcome of the operation. If the abort-on-open-error mode is in effect (the default situation), the only possible value of error is 0. input common-fcb INT:ref:* is an array of FCBSIZE or FCBSIZE^D00 words for use by the SIO procedures. Only one common file control block (FCB) is used per process.
OPEN^FILE Procedure Guardian Procedure Calls (O) • If block-buffer is not being used for any of the other three purposes, then the array is used for SIO record blocking and deblocking. No blocking is performed if any of the following occurs: • • • block-buffer or block-bufferlen is omitted. The value of block-bufferlen is insufficient according to the record length for the file. Read/write access is indicated.
Guardian Procedure Calls (O) OPEN^FILE Procedure corresponding to the flags parameter. A 0 indicates the default setting is used. If this parameter is omitted, all positions are treated as zeros. max-recordlen input INT:value specifies the maximum record length for records within this file. If this parameter is omitted, the maximum record length is 132.
OPEN^FILE Procedure Guardian Procedure Calls (O) When using OPEN^FILE to access a temporary disk file, AUTO^CREATE must be OFF; otherwise, the OPEN^FILE call results in a file-system error 13. • Sync depth of open files All files opened with the OPEN^FILE procedure are opened with a sync depth of 1. This is the only possible sync depth; no other can be set. • Opening $RECEIVE If you attempt to use a C-series format common FCB with a D-series format FCB for $RECEIVE, OPEN^FILE fails with an error 536.
OPEN^FILE Procedure Guardian Procedure Calls (O) then a file code of 0 is used. (See “EDIT File Considerations,” later.) The default extent sizes are 8 pages for the primary extent and 32 pages for the secondary extent. The maximum number of extents is 500. AUTO^TOF (%100D) Auto top of form; defaults to ON. If ON and the file is a line printer or process that is open with write access, a page eject is issued to the file within the OPEN^FILE procedure. BLOCKED (%400D) Nondisk blocking; defaults to OFF.
OPEN^FILE Procedure Guardian Procedure Calls (O) PRINT^ERR^MSG (%4D) Print error message; defaults to ON. If ON, and a fatal error occurs, an error message is displayed on the error file. This file is the home terminal unless otherwise specified. PURGE^DATA (%40D) Purge data; defaults to OFF. If ON, and open access is write, the data is purged from the file after the open. If OFF, the new data is appended to the existing data. READ^TRIM (%2000D) Read trailing blank trim; defaults to ON.
Guardian Procedure Calls (O) OPEN^FILE Procedure the value of EOF is greater) when compared to the same file managed by SIO prior to 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.
Guardian Procedure Calls (O) OPEN^FILE Procedure Related Programming Manual For programming information about the OPEN^FILE procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (O) OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure ) OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (O) OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure ) 11 File does not exist; indicates that the file does not exist and that the flags parameter indicates read-only access to the file. 14 Device does not exist; indicates that the device-name part of the file name designates a device that either does not exist or is not a disk device.
Guardian Procedure Calls (O) OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure ) input flags INT:value specifies the value that is passed to the flags parameter of the OPEN procedure if OPENEDIT opens the file. The following 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.
Guardian Procedure Calls (O) OPENEDIT Procedure (Superseded by OPENEDIT_ Procedure ) 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 flags, syncdepth, and write-thru parameters to OPENEDIT are ignored.
OPENEDIT_ Procedure Guardian Procedure Calls (O) OPENEDIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (O) -2 -3 -4 -5 OPENEDIT_ Procedure Page-table tags are out of order. Page-table tag is outside legal range. Page-table block number is outside of file. Page table has duplicate block numbers. 11 File does not exist; indicates that the file does not exist and that the access parameter indicates read-only access to the file. 14 Device does not exist; indicates that the device-name part of the file name designates a device that either does not exist or is not a disk device.
Guardian Procedure Calls (O) OPENEDIT_ Procedure FILE_CREATE_, if necessary), and then creates the internal IOEdit data structures. On return, if OPENEDIT_ called FILE_OPEN_, the returned value is the number returned by FILE_OPEN_ to identify the open file. If OPENEDIT_ did not call FILE_OPEN_, the input value of filenum is returned unchanged. input access INT:value specifies the value that is passed to the access parameter of the FILE_OPEN_ procedure if OPENEDIT_ opens the file.
Guardian Procedure Calls (O) OPENEDIT_ Procedure Refer to the nowait-depth parameter under the FILE_OPEN_ procedure for a detailed description of this parameter. Refer to “Nowait Considerations” under the INITIALIZEEDIT procedure for a description of how opening a file for nowait access affects an edit file. input sync-depth 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.
Guardian Procedure Calls (O) OPENEDIT_ Procedure Example In the following example, OPENEDIT_ calls FILE_OPEN_ for the file $MYVOL.TEST.AFILE. The following default values are used: read-only, shared access, nowait mode, sync depth of 0, and no unbuffered writes. STRING .EXT fname[0:16] := [ “$MYVOL.TEST.AFILE” ]; INT length := 17; INT .EXT fnumber := -1; . .
Guardian Procedure Calls (O) OPENER_LOST_ Procedure OPENER_LOST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (O) OPENER_LOST_ Procedure Syntax for TAL Programmers status := OPENER_LOST_ ( message:length ,table ,index ,number-of-entries ,entry-size ); ! ! ! ! ! i:i i i,o i i Parameters returned value status INT indicates the result of the search.
Guardian Procedure Calls (O) OPENER_LOST_ Procedure input table INT .EXT:ref:* points to the beginning of the open table to be searched. If the process handles of the primary and backup openers are not stored in the first 20 words of each table entry, table must point to the process handle of the first primary opener, not to the beginning of the table. See “Considerations.” input, output index INT .EXT:ref:* on input, contains an index indicating at what point in the open table the search is to begin.
OPENER_LOST_ Procedure Guardian Procedure Calls (O) • • • • Entries are of fixed length and are entry-size long. The process handles of the primary and backup openers are stored back-toback (the primary preceding the backup) in contiguous 10-word fields within each entry. If the primary and backup process handles are not the first fields in the entry, table points to the first word of the first entry’s primary-opener process handle rather than to the first word of the table entry.
Guardian Procedure Calls (O) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations OSS Considerations Example Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (O) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) Parameters returned value error INT is the file-system error number indicating the outcome of the call. Error 1 (EOF) indicates there are no further opens. Error 2 (invalid operation) is returned for nondisk devices that cannot return any valid information. input searchname INT:ref:12 is the internal-format file name of the disk volume or disk file whose open information is being requested.
Guardian Procedure Calls (O) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) output exclusion INT:ref:1 is the exclusion mode with which the file is open. The codes are: 0 1 2 3 shared exclusive process exclusive (supported only for Optical Storage Facility) protected output syncdepth INT:ref:1 is the sync depth specified when the file was opened. output file-name INT:ref:12 is the internal-format file name of the file which is open.
Guardian Procedure Calls (O) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) Considerations • Order of returned information Opens are not returned in any defined order. In particular, when retrieving information about all opens on a disk volume, the opens for any one file are not grouped together in the sequence of calls.
Guardian Procedure Calls (O) OPENINFO Procedure (Superseded by FILE_GETOPENINFO_ Procedure ) OSS Considerations It is often necessary to run OSS processes at high PINs. See “Considerations,” earlier, for more information.
Guardian Procedure Calls (O) OSS_PID_NULL_ Procedure OSS_PID_NULL_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters OSS Considerations Summary The OSS_PID_NULL_ procedure returns a null OSS process ID.
12 Guardian Procedure Calls (P) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter P. Table 12-1 lists all the procedures in this section. Table 12-1.
Guardian Procedure Calls (P) Table 12-1.
PACKEDIT Procedure Guardian Procedure Calls (P) 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.
Guardian Procedure Calls (P) PACKEDIT Procedure unpacked-length input INT:value specifies the length in bytes of unpacked-line. output packed-line STRING .EXT:ref:* is a string array that contains the line in packed format that is the outcome of the conversion. The length of the packed line is returned in the packed-length parameter. packed-limit input INT:value specifies the length in bytes of the string variable packed-line. packed-length output INT .
Guardian Procedure Calls (P) PATHNAME_TO_FILENAME_ Procedure PATHNAME_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters OSS Considerations Example in C Related Programming Manual Summary The PATHNAME_TO_FILENAME_ procedure converts an OSS pathname to a Guardian file name. See Appendix D, File Names and Process Identifiers, for a description of the OSS pathname syntax.
Guardian Procedure Calls (P) PATHNAME_TO_FILENAME_ Procedure 4006 A prefix within pathname refers to an OSS fileset other than the root fileset that is not mounted. The corresponding OSS errno value is ENXIO. 4013 Search permission is denied on a component of the pathname prefix. The corresponding OSS errno value is EACCESS. 4014 A specified parameter has an invalid address. The corresponding OSS errno value is EFAULT. 4020 A prefix within pathname refers to a file other than a directory.
PATHNAME_TO_FILENAME_ Procedure Guardian Procedure Calls (P) output length 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. output info-flags INT .EXT:ref:1 contains additional information about the file.
PATHNAME_TO_FILENAME_ Procedure Guardian Procedure Calls (P) • The resident memory used by the calling process increases by a small amount.
Guardian Procedure Calls (P) POOL_CHECK_ Procedure POOL_CHECK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_CHECK_ procedure checks the internal pool data structures and returns error information.
Guardian Procedure Calls (P) POOL_CHECK_ Procedure 3 Bounds error. A parameter on the parameter list has a bounds error. 9 Corrupt pool header. 11 Corrupt allocated blocks. Data is probably written beyond the allocated block. 12 Corrupt free list blocks. Data is probably written into a returned block. input pool INT .EXT:ref:* is the address of the pool as specified in the call to the POOL_DEFINE_ procedure. corruption-address output EXTADDR .
Guardian Procedure Calls (P) POOL_CHECK_ Procedure output tag-size INT .EXT:ref:1 is the size in bytes of a boundary tag that defines the beginning or end of a block. Considerations See “Considerations” for the POOL_DEFINE_ procedure. Example error := POOL_CHECK_( pool, corruption^addr, pblock ); Related Programming Manual For programming information about the POOL_CHECK_ memory-management procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (P) POOL_DEFINE_ Procedure POOL_DEFINE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_DEFINE_ procedure designates a portion of a user’s stack or an extended data segment for use as a pool.
Guardian Procedure Calls (P) POOL_DEFINE_ Procedure 3 Bounds error. pool is in a read-only segment, or pool-size is larger than the space available. 4 Invalid size. pool-size is too small to allocate the minimum size pool including the pool header. 5 Alignment error on pool. pool is not in alignment with the selected alignment. 6 Invalid alignment. alignment is not 0, 4, 8, or 16. input pool INT .
Guardian Procedure Calls (P) POOL_DEFINE_ Procedure Considerations Note. There are additional considerations for privileged callers. • Internal variable-length pool header The POOL_DEFINE_ procedure creates an internal variable-length pool header at the beginning of the pool. The length of the header can change between RVUs or processor types. Information in the header is retrieved by calling the POOL_GETINFO_ procedure; the header should not be accessed directly, since it is subject to change.
Guardian Procedure Calls (P) POOL_DEFINE_ Procedure Each block allocated by the POOL_GETSPACE_ procedure has a tag at the beginning of the block and a tag at the end of the block. A block boundary tag serves three purposes: • • • • It contains the size of each block so that the program does not need to specify the length of a block when releasing it.
POOL_GETINFO_ Procedure Guardian Procedure Calls (P) POOL_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_GETINFO_ procedure returns information about the specified pool.
Guardian Procedure Calls (P) POOL_GETINFO_ Procedure Parameters returned value error INT indicates the 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. input pool INT .
Guardian Procedure Calls (P) POOL_GETINFO_ Procedure fail-block-size output INT(32) .EXT:ref:1 is the size in bytes of the block that the POOL_GETSPACE_ procedure failed to allocate when it returned an error value of 10 (unable to allocate space). Note that the value of the block-size parameter specified in the POOL_GETSPACE_ procedure is smaller than fail-block-size because it is not rounded up.
Guardian Procedure Calls (P) POOL_GETSPACE_ Procedure POOL_GETSPACE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_GETSPACE_ procedure obtains a block of memory from a buffer pool.
Guardian Procedure Calls (P) POOL_GETSPACE_PAGE_ Procedure (H-Series RVUs Only) input block-size INT(32):value is the size in bytes of the memory to be obtained from the pool. This value can range from 1 byte through the available space in the pool. The block size of the allocated block can be rounded up to retain the alignment of the pool. output error INT .EXT:ref:1 indicates the outcome of the call: 0 No error. 2 Required parameter missing. 4 Invalid size.
Guardian Procedure Calls (P) POOL_GETSPACE_PAGE_ Procedure (H-Series RVUs Only) Summary The POOL_GETSPACE_ 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.
Guardian Procedure Calls (P) POOL_GETSPACE_PAGE_ Procedure (H-Series RVUs Only) 4 Invalid size. size is not within the valid range. 9 Corrupt pool header. 10 Unable to allocate space.
Guardian Procedure Calls (P) POOL_PUTSPACE_ Procedure POOL_PUTSPACE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_PUTSPACE_ procedure returns a block of memory to a buffer pool.
Guardian Procedure Calls (P) POOL_PUTSPACE_ Procedure input pool INT .EXT:ref:* is the address of the pool as specified in the call to the POOL_DEFINE_ procedure. When POOL_PUTSPACE_ is called, the pool header is updated. input block INT .EXT:ref:* is the address of the block to be returned to the pool. Considerations POOL_GETSPACE_ and POOL_PUTSPACE_ do not check pool data structures on each call.
Guardian Procedure Calls (P) POOL_RESIZE_ Procedure POOL_RESIZE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The POOL_RESIZE_ procedure changes the size of a pool that was initialized by the POOL_DEFINE_ procedure.
Guardian Procedure Calls (P) POOL_RESIZE_ Procedure 11 Corrupt allocated blocks. Data is probably written beyond the allocated block. 12 Corrupt free list blocks. Data is probably written into a returned block. 13 Unable to shrink pool. input pool INT .EXT:ref:* is the address of the pool as specified in the call to the POOL_DEFINE_ procedure. When POOL_RESIZE_ is called, the pool header is updated.
POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) Guardian Procedure Calls (P) 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.
POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) Guardian Procedure Calls (P) Syntax for TAL Programmers CALL POSITION ( filenum ,record-specifier ); ! i ! i Parameters input filenum INT:value is the number of an open file that identifies the file where the positioning is to take place. input record-specifier INT(32):value is the 4-byte value that specifies the new setting for the current-record and nextrecord pointers. Relative Files record-specifier is a 4-byte record-num..
POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) Guardian Procedure Calls (P) Entry-Sequenced Files The record-specifier is a 4-byte record-addr (the primary key), whose format depends upon the file's block size as follows: Block size Number of bits for block number Number of bits for the relative record number within that block 4096 20 12 2048 21 11 1024 22 10 512 23 9 In all cases, the block number occupies the leftmost bits, and the record number occupies the rightmost bit
Guardian Procedure Calls (P) POSITION Procedure (Superseded by FILE_SETPOSITION_ Procedure) Unless the unstructured file is created with the odd unstructured attribute (also known as ODDUNSTR) set, the RBA passed in record-specifier must be an even number. If the odd unstructured attribute is set when the file is created, the RBA passed in record-specifier can be either an odd or even value.
Guardian Procedure Calls (P) POSITIONEDIT Procedure POSITIONEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (P) POSITIONEDIT Procedure record-number input INT(32):value specifies the value to which the file’s next record number is to be set. This value is 1000 times the EDIT line number of the intended record. You can specify -1 to indicate positioning to the beginning of the file; you can specify -2 to indicate positioning to the end of file. Example In the following example, POSITIONEDIT sets the next record number to indicate line 500 in the specified file.
Guardian Procedure Calls (P) PRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure PRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure or PROCESS_GETINFOLIST_ 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. The PRIORITY procedure enables a process to examine or change its initial priority.
Guardian Procedure Calls (P) PRIORITY Procedure (Superseded by PROCESS_SETINFO_ Procedure new-priority input INT:value specifies a new execution priority value in the range {1:199} for this process. If omitted, the initial priority remains unchanged. init-priority output INT:ref:1 returns the initial run priority of the process when it was started. Considerations • • A caller of PRIORITY executing in privileged mode can set its priority to a value greater than 199.
Guardian Procedure Calls (P) PROCESS_ACTIVATE_ Procedure PROCESS_ACTIVATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESS_ACTIVATE_ Procedure processhandle input INT .EXT:ref:10 is a process handle that specifies the process to be activated: • • To activate a single process, specify the process handle of that process. To activate a process pair, specify the process handle of either the primary or backup process. input specifier INT:value for a named process pair, indicates whether both members should be activated. Valid values are: 0 Activate the specified process.
Guardian Procedure Calls (P) PROCESS_ACTIVATE_ Procedure When PROCESS_ACTIVATE_ is called on an OSS process, the security rules that apply are the same as those that apply when the OSS kill() function is called. See the kill(2) function reference pages either online or in the Open System Services System Calls Reference Manual for details. Safeguard Considerations For information on processes protected by Safeguard, refer to the Safeguard Reference Manual.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Nowait Considerations Compatibility Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations Example Related Programming Manuals Summary Note.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Syntax for C Programmers #include short PROCESS_CREATE_ ( [ const char *program-file ]/* i,i1*/ ,[ short length ] /* i,i1*/ ,[ const char *library-file ] /*i,i 2*/ ,[ short length ] /* i,i2*/ ,[ const char *swap-file ] /* i,i3*/ ,[ short length ] /* i,i3*/ ,[ const char *ext-swap-file ] /* i,i4*/ ,[ short length ] /* i,i4*/ ,[ short priority ] /* i 5*/ ,[ short processor ] /* i 6*/
PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (P) Syntax for TAL Programmers error := PROCESS_CREATE_ ( [ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ ,[ program-file: length ] ! i,i 1 library-file: length ] ! i:i 2 swap-file: length ] ! i:i 3 ext-swap-file: length ! i:i 4 priority ] ! i 5 processor ] ! i 6 processhandle ] ! o 7 error-detail ] ! o 8 name-option ] ! I 9 name: length ] ! i:i10 process-descr: maxlen ]!o:i 11 process-descr-len ] ! o 12
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) library-file:length input:input STRING .EXT:ref:*, INT:value if supplied and if length is not 0 or -1, specifies the name of the user library file to be used by the process. If used, the value of library-file must be exactly length bytes long. If the library file name is partially qualified, it is resolved using the =_DEFAULTS DEFINE.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) exactly length 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. See “Considerations” for more information about swap files. input:input ext-swap-file:length STRING .
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) output processhandle 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. output error-detail INT .EXT:ref:1 returns additional information about some classes of errors.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) For other values of name-option, this parameter should be omitted (or length should be set to 0), since the system will either generate a name or, in the case of backup creation, use the name of the caller. process-descr:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns a process descriptor suitable for passing to FILE_OPEN_.
PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (P) For native processes, this parameter is ignored. To specify the maximum size of the main stack, create a new process using the PROCESS_LAUNCH_ procedure and specify the Z^MAINSTACK^MAX field of the param-list parameter. Alternatively, use the nld utility to set the TNS/R process attributes or the eld utility to set the TNS/E process attributes .
PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (P) <15> = 1 DEFINEs enabled (ignored if bit 13 is 0). = 0 Can run at any PIN. = 1 Requires low PIN (in range 0 through 254). The default value is 0. If you specify create-options.<9> = 1, the process deletion message (in the event that the created process terminates) is sent to any process that has the calling process’s name at that time, regardless of the sequence number. If you specify create-options.
PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Guardian Procedure Calls (P) input debug-options INT:value sets the debugging attributes for the new process. The fields are: <0:11> Reserved (specify 0) <12> 1 0 Enter Debug or the Inspect debugger at the first executable instruction of the program's MAIN procedure. Begin normal program execution. <13> 1 0 If the process traps, create a saveabend file. If the process traps, do not create a saveabend file.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) appropriate attribute of the DEFINE, the resolved name will include the caller’s node. See below for details on resolution of specific file-name parameters. • For TNS and accelerated processes on RVUs preceding the D42.
Guardian Procedure Calls (P) • PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Device subtypes for named processes (process subtypes) The device subtype (or process subtype) is a program file attribute that can be set by a TAL compiler directive at compile time, nld flag at link time, or Binder command at bind time. You can obtain the device type and subtype of a named process by calling FILE_GETINFO[BYNAME]_ , FILEINFO, or DEVICEINFO.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) Nowait Considerations • If you call this procedure in a nowait manner, the results are returned in the nowait PROCESS_LAUNCH_ or PROCESS_CREATE_ completion message (-102), not the output parameters of the procedure. The format of this completion message is described in the Guardian Procedure Errors and Messages Manual. If error is not 0, no completion message is sent to $RECEIVE.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) propagated; otherwise, the =_DEFAULTS DEFINE in the caller’s context is propagated. Buffer space for DEFINEs being propagated to a new process is limited to 256 KB 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.
Guardian Procedure Calls (P) PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) the new process. If the caller is part of a batch job, to start a new process that is part of the caller’s batch job, omit jobid or set it to -1. • • 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.
Guardian Procedure Calls (P) • • • PROCESS_CREATE_ Procedure (Superseded by PROCESS_LAUNCH_ Procedure ) 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.
PROCESS_DEBUG_ Procedure Guardian Procedure Calls (P) PROCESS_DEBUG_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESS_DEBUG_ Procedure Parameters returned value error INT returns a file-system error number indicating the outcome of the process debug attempt. Possible values include the following: 0 11 48 201 640 Debug request accepted. If the process to be debugged is not the calling process, the request might have been queued. Process does not exist. Security violation. Unable to communicate with the processor of the process.
Guardian Procedure Calls (P) PROCESS_DEBUG_ Procedure Considerations • The caller of PROCESS_DEBUG_ must be the super ID, the group manager of the process access ID, or a process with the same process access ID as the specified process or process pair. For information about the process access ID, refer to the description under “Considerations” for the PROCESS_GETINFO_ procedure and the Guardian User’s Guide. The caller must be local to the same system as the specified process.
Guardian Procedure Calls (P) • • Issuing a DEBUG command to a TACL process running at another local terminal. You can use Inspect by setting the Inspect attribute associated with a process.
Guardian Procedure Calls (P) PROCESS_DELAY_ Procedure (H-Series RVUs Only) authenticated from the viewpoint of the system where the target process is executing. • • • • The caller has read access to the program file and any library files. The program does not contain PRIV or CALLABLE routines. The target is not a system process. The now parameter is not specified. Only program file owners and users with appropriate privileges are able to debug programs that set the user ID.
PROCESS_DELAY_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (P) Syntax for C Programmers #include void PROCESS_DELAY_ ( long long (Timeout ); Syntax for TAL Programmers PROC PROCESS_DELAY_( MUTIME ) CALLABLE, RESIDENT; long long MUTIME; EXTERNAL; -- INPUT: TIMEOUT IN MICROSECONDS Parameters input timeout long long:value specifies the time, in microsecond units, that the caller of PROCES_DELAY_ is to be suspended.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure PROCESS_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Mom Considerations Home Terminal Considerations I/O Processes That Control Multiple Devices OSS Considerations Example Related Programming Manual Summary The PROCESS_GETINFO_ procedure obtains a limited set of information about a specified process.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure 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.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure Syntax for TAL Programmers ! ! error := PROCESS_GETINFO_ ( [ processhandle ] ,[ proc-fname: maxlen ] ,[ proc-fname-len ] ,[ priority ] ,[ mom's-processhandle ] ,[ hometerm: maxlen ] ,[ hometerm-len ] ,[ process-time ] ,[ creator-access-id ] ,[ process-access-id ] ,[ gmom's-processhandle ] ,[ jobid ] ,[ program-file: maxlen ] ,[ program-len ] ,[ swap-file: maxlen ] ,[ swap-len ] ,[ error-detail ] ,[ proc-type ] ,[ oss-pid ] ); ! Input Error Output De
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure proc-fname:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns the process file name of the target process. Normally, this value is a process descriptor. However, if the specified process is an I/O process (that is, a process that controls a device or volume), the returned value is the fully qualified device or volume name. maxlen is the length in bytes of the string variable proc-fname.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure output creator-access-id INT .EXT:ref:1 returns the creator access ID of the specified process. See “Considerations” for information about the creator access ID. output process-access-id INT .EXT:ref:1 returns the process access ID of the specified process. See “Considerations” for information about the process access ID. output gmom's-processhandle INT .EXT:ref:10 returns the process handle of the job ancestor (GMOM) of the specified process.
PROCESS_GETINFO_ Procedure Guardian Procedure Calls (P) output:input swap-file:maxlen STRING .EXT:ref:*, INT:value returns $volume.#0. Processes do not swap to $volume.#0; they swap to a swap file managed by the Kernel-Managed Swap Facility. For more information on this facility, refer to the Kernel-Managed Swap Facility (KMSF) Manual. For TNS processes on RVUs preceding the D42 RVU, swap-file returns the internal-format file name of the swap file for the process’s data segment.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure General Considerations • Process access ID (PAID) and creator access ID (CAID) An access ID is a word associated with a given process that contains a group ID number in the left byte and a user ID number in the right byte. Two types of access IDs are used in the operating system. The process access ID (PAID) is returned by PROCESS_GETINFO_ and is normally used for security checks when a process attempts to access a disk file.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure 6. hometerm or maxlen 7. hometerm-len 8. process-time 9. creator-access-id 10. process-access-id 11. gmom’s-processhandle 12. jobid 13. program-file or maxlen 14. program-len 15. swap-file or maxlen 16. swap-len 17. error-detail 18. proc-type 19.
Guardian Procedure Calls (P) PROCESS_GETINFO_ Procedure a mom process if a mom process has been explicitly assigned by either the PROCESS_SETINFO_ or STEPMOM procedure. Home Terminal Considerations • • The home-terminal file name returned by PROCESS_GETINFO_ is in a form suitable for passing directly to file-system procedures such as FILE_OPEN_.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure PROCESS_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Attribute Codes and Value Representations OSS Considerations Example 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.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure 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
Guardian Procedure Calls (P) • PROCESS_GETINFOLIST_ Procedure The parameter length specifies the length in bytes of the character string pointed to by nodename. The parameters nodename and length must either both be supplied or both be absent.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure which information has been returned (might be more than one process if in search mode). If no search criteria were specified, no information was returned and error-detail contains 0. 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).
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure If srch-option is omitted or 0, the caller is requesting information about process pin. If srch-option is 1 or 2, the caller wants to search the processes in cpu for those that match a set of criteria (such as having a particular user ID and program file name). In this case, pin is used to indicate where to begin searching, and is usually set to 0 on the initial call.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure processhandle input INT .EXT:ref:10 if present and not null (-1 in each word), is an input parameter specifying the process handle of the process of interest. If a value is supplied for processhandle, then srch-option must be omitted or 0, nodename:length must be omitted or length must be 0, cpu and pin must be omitted or -1, and oss-pid must be omitted or null (a null OSS process ID is obtained by calling the OSS_PID_NULL_ procedure).
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure Whenever srch-option is 1 or 2, the caller should either include the PIN (38) or OSS process ID (90) attribute in the set of requested attributes in order to identify the Guardian or OSS process associated with each set of returned values. input ret-values-maxlen INT:value is the maximum length in words of ret-values-list. Valid values for the ret-values-maxlen parameter are in the range 0 through 8192. ret-values-len output INT .
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure returned, the value of error-detail is 0 and the value of pin, if specified, is -1; the values of all other output parameters are indeterminate. srch-attr-list input INT .EXT:ref:* is an array of integer attribute codes specifying the items that are included in the search criteria. This parameter must be supplied if srch-option is 1 or 2. This parameter is ignored if srch-option is 0 or 3.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure If a value is supplied for oss-pid, then srch-option must be 3, processhandle must be omitted or null (-1 in each word), and cpu and pin must be omitted or -1. This parameter is ignored if srch-option is 0,1, or 2. General Considerations • • • • All considerations listed under PROCESS_GETINFO_ also apply to PROCESS_GETINFOLIST_. You must qualify any file names used as search attributes.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) An iterative attribute must be the last one in the attribute list. If it is not, an error is reported. Iterative attributes cannot be used with srch-option 1 or 2. Loadfile Types Several attributes return information about loadfiles, including the loadfile type.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Using the Loadfile Type Code Values The type code value returned is one of the values 0 through 8 plus other values as appropriate.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-2.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-2.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure Table 12-2.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-2.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure Except for attributes 125 and 126, all file names that are specified as search parameters are assumed to be sufficiently qualified and are not resolved against defaults. They are interpreted 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, then the home terminal name in the search list must be \A.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) See “Considerations” for the PROCESS_CREATE_ procedure for more information about process subtypes. • 9: minimum priority as a search attribute, specifies the minimum priority of interest. Minimum priority cannot be specified as a return attribute code. • 10: process state as a search attribute, specifies the process state.
Guardian Procedure Calls (P) <5:15> PROCESS_GETINFOLIST_ Procedure (reserved) This attribute and the process state attribute (32) return the same information for bit <0>. • 12: earliest creation time as a search attribute, specifies the earliest process-creation time (in Julian timestamp format) of interest. This cannot be used as a search attribute if the target system is running an operating system version earlier than D10. Earliest creation time cannot be specified as a return attribute code.
Guardian Procedure Calls (P) 5 6 7 • PROCESS_GETINFOLIST_ Procedure Process is on the DMON list waiting for an Inspect request or waiting to create a saveabend file. Process is on the cleanup list waiting to clean up resources before deletion. Process is on the binary semaphore list waiting for a binary semaphore. 21: real group ID as a search attribute, specifies the real group ID. When used as a return attribute, this attribute returns the real group ID of the process.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure as a search attribute, specifies the session leader. When used as a return attribute, this attribute returns the session leader. The session leader returned might identify a process that is no longer valid. The session leader is an OSS process that has created a session. A session is a collection of process groups established for job-control purposes. Each process group is a member of a session.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) • 30: process time See the process-time parameter returned by the PROCESS_GETINFO_ procedure. • 31: wait state returns the wait field of the process indicating what, if anything, the process is waiting on.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) 11 12 13 14 Inspect request saveabend terminating XIO initialization (not applicable on G-series RVUs) The OSS zombie process state has no Guardian equivalent. This attribute and the process list attribute (15) return the same information for bit <2>. This attribute and the process state attribute (10) return the same information for bits <11:15>.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure returns 0 in bit 15 if the program file of the process was not licensed when the process was created; returns 1 if the program file of the process was licensed when the process was created. Bits <0:14> are reserved and should not be assumed to contain 0. • 38: PIN returns the PIN of the process whose attributes are being returned. This attribute should be specified whenever srch-option is not 0.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure returns 1 in bit <15> if the process is logged on, 0 if not. Bits <0:14> are reserved and should not be assumed to contain 0. • 46: extended swap file returns the name of the swap file for the selectable segment that is currently in use. If the process is in the starting or terminating stage, or, if its program file or libraries are being loaded by RLD, then a file name length of 0 is returned.
Guardian Procedure Calls (P) • PROCESS_GETINFOLIST_ Procedure 54: current pages returns the number of memory pages that have been swapped in by the process and are still resident. • 55: messages sent in G-series systems, returns the number of messages sent by this process since the Measure product started collecting statistics on the process. If the Measure product is not collecting statistics on the process, -1D is returned.
Guardian Procedure Calls (P) 2 • PROCESS_GETINFOLIST_ Procedure No other process can stop the process. 64: stop request queue returns the status of a stop request on the queue. See the PROCESS_STOP_ procedure for more information on the stop request queue. 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.
Guardian Procedure Calls (P) <9> <10> <11> <12> <13> <14> <15> • PROCESS_GETINFOLIST_ Procedure Propagate stop-on-logoff Propagate logon Stop on logoff Inherited logon Safeguard-authenticated logoff Safeguard-authenticated logon Logged-on state 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.
Guardian Procedure Calls (P) • PROCESS_GETINFOLIST_ Procedure 82: login name returns the login name. The login name is a user name associated with a login. A byte length of 0 is returned if the process (or the process that created the target process) did not log in, or if the target process is created using an operating system version earlier than D30. This attribute is undefined if the target system is running an operating system version earlier than D30.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure This attribute applies only to OSS processes on the same node as the calling process. This attribute is undefined if the target system is running an operating system version earlier than D30. • 94: OSS parent process ID (OSS processes only) returns the OSS process ID of the OSS parent process; otherwise it returns the null OSS process ID (a null OSS process ID is obtained by calling the OSS_PID_NULL_ procedure).
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure returns the OSS process ID of the OSS process group leader; otherwise, it returns the null OSS process ID (a null OSS process ID is obtained by calling the OSS_PID_NULL_ procedure). The OSS group leader process ID might identify a process that is no longer active. This attribute is undefined if the target system is running an operating system version earlier than D30.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure returns the current privileged stack size in bytes. 0D is returned if the target system is running an operating system version earlier than D40.
Guardian Procedure Calls (P) • PROCESS_GETINFOLIST_ Procedure 107: maximum privileged stack size returns the maximum privileged stack size in bytes. 0D is returned if the target system is running an operating system version earlier than D40. • 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. • 109: size of global data returns the size of global data in bytes.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) • 116: Native shared run-time library file-name information returns information on native shared run-time library file names used by the process in the following variable-sized array: TAL Value Representation Description INT Number of file names returned. This value indicates how many triplets of INT, INT, and STRING, as listed below, follow this value.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) • 118: Native shared run-time library name information returns information about native shared run-time library names used by the process in the following variable-sized array: TAL Value Representation • Description INT Number of names returned. This value indicates how many triplets of INT, INT, and STRING, as listed below, follow this value.
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) The loadfile information array contains the following 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 on page 12-78) Result value for TAL programs: For TAL programs, the result value is an instance of ZSYS^PINF^LOADFILE^INFO^DEF, in whic
PROCESS_GETINFOLIST_ Procedure Guardian Procedure Calls (P) an eight-byte context value as auxiliary data. The attribute code must include the length indication, so its value is 16507 or (4<<12)+123. On a TNS/R system, this attribute returns ten bytes of zero, so the number of loadfiles reported and the context are zero. On a TNS/R system, this attribute returns ten bytes of zero, so the number of loadfiles reported and the context are zero.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure For TAL programs, the result value is an instance of ZSYS^PINF^LOADFILE^DETAIL^DEF. This structure is declared in ZSYSTAL section PROCESS^GETINFOLIST^RETURN. Result value for C programs: For C programs, the result value is an instance of zsys_pinf_loadfile_detail_def. This structure is declared in ZSYSC section process_getinfolist_return. This attribute cannot be specified with a srch-option of 1 or 2.
Guardian Procedure Calls (P) • PROCESS_GETINFOLIST_ Procedure 125: processes that have loaded the specified Guardian loadfile This is a search-only attribute used to find processes that have loaded a particular loadfile. The Guardian file name must be specified in srch-values-list. If the file name is not fully qualified, the current =_DEFAULTS DEFINE is used to specify the omitted system, volume, and subvolume.
Guardian Procedure Calls (P) PROCESS_GETINFOLIST_ Procedure Example attr^list := 8; ! get subdevice type only attr^count := 1; ret^vals^maxlen := 1; error := PROCESS_GETINFOLIST_ ( , , , prochandle, attr^list, attr^count, ret^vals^list, ret^val^maxlen, ret^val^length ); Related Programming Manual For programming information about the PROCESS_GETINFOLIST_ procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure PROCESS_GETPAIRINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure 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.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure Syntax for TAL Programmers error := PROCESS_GETPAIRINFO_ ( [ processhandle ] ,[ pair: maxlen ] ,[ pair-length ] ,[ primary-processhandle ] ,[ backup-processhandle ] ,[ search-index ] ,[ ancst-processhandle ] ,[ search-nodename: length ] ,[ options ] ,[ ancst: maxlen ] ,[ ancst-length ] ,[ error-detail ] ); !i 1 !i,o:i 2 !o 3 !o 4 !o 5 !i,o 6 !o 7 !i:i 8 !i 9 !i,o:i10 !o 11 !o ! ! ! ! ! ! ! ! ! ! ! 12 ! Parameters returned value error INT ind
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure input processhandle INT .EXT:ref:10 if supplied, is a process handle specifying the process of interest. You can specify either the primary or backup process when seeking information about a process pair. processhandle is ignored if the search-index parameter is present. If processhandle is omitted or null (-1 in each word) and search-index is not present: • • If pair:maxlen is present, it specifies the process or process pair of interest.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure output pair-length INT .EXT:ref:1 if pair:maxlen is an output parameter, contains the length in bytes of the value returned in pair. output primary-processhandle INT .EXT:ref:10 returns the process handle of the primary process of a named process pair or (if the specified process is a single named process) the process handle of a single named process.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure search-nodename:length input:input STRING .EXT:ref:*, INT:value if length is not 0 and search-index is present, specifies the name of the node on which the search is to take place. PROCESS_GETPAIRINFO_ uses searchnodename to determine the node to search on each call, so its contents should not be altered between calls. The value of search-nodename must be exactly length bytes long and must be a valid node name.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure output error-detail INT .EXT:ref:1 returns additional information about some classes of errors. See the list under error for details. 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.
Guardian Procedure Calls (P) PROCESS_GETPAIRINFO_ Procedure Example error := PROCESS_GETPAIRINFO_ ( prochandle, , , primary, backup ); Guardian Procedure Calls Reference Manual—522629-013 12- 115
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure PROCESS_LAUNCH_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for param-list Structure Definition for output-list General Considerations Nowait Considerations DEFINE Considerations Batch Processing Considerations Safeguard Considerations OSS Considerations Related Programming Manuals Summary The PROCESS_LAUNCH_ procedure creates a new process and, optionally, assigns a number of process attribut
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Syntax for TAL Programmers error:= PROCESS_LAUNCH_ ( param-list ! i 1 ! ,[ error-detail ] ! o 2 ! ,[ output-list:maxlen ]! o:i 3 ! ,[ output-list-len ] ); ! o 4 ! Parameters returned value error INT indicates the outcome of the operation. Table 12-3 on page 12-118 summarizes possible values for error. input param-list INT .
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure output-list-len output INT .EXT:ref:* returns the length, in bytes, of the structure returned in output-list. Table 12-3. Summary of Process Creation Errors (page 1 of 10) error Description 0 No error; process created, or creation initiated if you are creating the process in a nowait manner. 1 File-system error on program file; error-detail contains a file-system error number*.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 2 of 10) Description error 10 Unable to communicate with system-monitor process; error-detail contains a file-system error number*. 11 Process-name error; error-detail contains a file-system error number*. Filesystem error 44 indicates that, when trying to create a named process, either the DCT is full or there are no system-generated names available.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 3 of 10) Description error 29 Unable to allocate a priv stack for the process. 30 Unable to lock the priv stack for the process. 31 Unable to allocate a main stack for the process. 32 Unable to lock the main stack of a native IOP. (This error is returned only to privileged callers.) 33 Security inheritance failure.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 4 of 10) error Description 47 The program file requires fixups to a shared run-time library (SRL) but the program file is currently running; error-detail contains the SRL number** of the unavailable SRL.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 5 of 10) Description error 63 There was an unresolved external reference for data. 64 Unable to honor floattype attribute. In G06.20 and later RVUs, this code is reported only for a program file; earlier RVUs use it also for librarles.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 6 of 10) Description error 9 The process abended while rld was running 10 The process stopped while rld was running 11 rld was licensed at the time the processor was loaded 12 rld returned an out-of-range error value to the operating system 16 The export digest of the file does not match the export digest of the impImp file in memory. 19 The user attempted to use RLD as a user library.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 7 of 10) Description error 78 8 The C++ version of the specified library conflicts with one or more loadfiles loaded for this process. 9 The loadfile is not licensed; license is required 10 A DLL for this process is licensed or privileged and has unprotected data which requires that all loadfiles in the process be licensed. Atleast one unlicensed loadfile exists in the process.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 8 of 10) Description error 79 80 A resource limitation was detected by the run-time loader (rld); error-detail contains one of the following: 1 The rld heap exceeded available KMSF space. 2 The rld heap exceeded its allocated address range. 3 The rld limit for handles was exceeded. (This error is reported for dynamic loading, not at process creation.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-3. Summary of Process Creation Errors (page 9 of 10) Description error 5 The public DLL has a priv or callable Main procedure 6 The public DLL does not support highpin. 7 The public DLL is not owned by super ID. 8 The public DLL has callable procedures and is not licensed. 9 A public DLL with this name has already been preloaded (duplicate name in zreg).
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) Table 12-3. Summary of Process Creation Errors (page 10 of 10) error Description 115 Unable to allocate global data or heap for the process (PROCESS_SPAWN_ only, prior to the G05 RVU). 116 Unable to propagate shared run-time library (SRL ) data (PROCESS_SPAWN_ only). 3xx Invalid file format on shared run-time library (SRL) number** xx; error-detail subcodes are described in Table 12-5.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) Table 12-4.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure The following table contains descriptions of the error subcodes for errors 12, 13, 70, 76, and 3xx. Table 12-5. Error Subcodes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (page 1 of 4) Subcode Meaning 1 The file is not a disk file.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-5. Error Subcodes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (page 2 of 4) Subcode Meaning 21 Accelerator header in the file is invalid. 22 Either UC (user code) or UL (user library) was accelerated with the wrong virtual address. 23 File has entry in native fixup list with invalid external entry-point (XEP) index value or invalid code address value.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-5. Error Subcodes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (page 3 of 4) Subcode Meaning 47 Either the TNS program needs to import data from the TNS user library and the library is not exporting any data, or the library needs global data space and the program is not providing it.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Table 12-5. Error Subcodes for Process Creation Errors 12, 13, 70, 76, 84, and 3xx (page 4 of 4) Subcode Meaning 68 One of the headers that is expected to be at the front of an ELF file did not fit near enough to the front. 69 This PIC ELF file is not supported on TNS/R systems: It is licensed or it contains callable functions. 70 The ELF file is too big (EOF > 2**31 bytes).
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Structure Definition for param-list The param-list parameter specifies the attributes of the new process.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) For TAL programs, the following default values, defined in the P_L_DEFAULT_PARMS_ define in the SYSTEM.DLAUNCH file, must be specified when an option is not wanted: Field Name Default Value Z^VERSION 1 Z^LENGTH $OFFSET(PROCESS_LAUNCH_PARMS_.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure In the C zsysc file, the structure for the param-list parameter is defined as: #pragma fieldalign shared2 __zsys_ddl_plaunch_parms typedef struct __zsys_ddl_plaunch_parms { short z_version; short z_length; zsys_ddl_char_extaddr_def z_program_name; long z_program_name_len; zsys_ddl_char_extaddr_def z_library_name; long z_library_name_len; zsys_ddl_char_extaddr_def z_swapfile_name; long z_swapfile_name_len; zsys_ddl_char_extaddr_def z_extswapfile_name;
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) Z^VERSION identifies the version of the ZSYS^DDL^PLAUNCH^PARMS structure. The following table summarizes the possible values for Z^VERSION. TAL literals are defined in the ZSYSTAL file. Literals in the zsysc file, for C programs, are the same as those for TAL except that they contain the underscore (_) character instead of the circumflex (^) character.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure If Z^LIBRARY^NAME is specified, unresolved external references are resolved first from the specified Z^LIBRARY^NAME, then from the system library. If Z^LIBRARY^NAME is specified and Z^LIBRARY^NAME^LEN is -1, then the linkage to the library file used by the process when it was last run is removed, and the process runs with no library file. (The references that were previously resolved from the user library are resolved from the system library.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Z^SWAPFILE^NAME^LEN specifies the length, in bytes, of the Z^SWAPFILE^NAME field. Z^EXTSWAPFILE^NAME for TNS processes, if not specified or Z^EXTSWAPFILE^NAME^LEN is 0, the Kernel-Managed Swap Facility (KMSF) allocates swap space for the default extended data segment of the process. For more information on this facility, refer to the Kernel-Managed Swap Facility (KMSF) Manual.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Z^HOMETERM^NAME^LEN specifies the length, in bytes, of the Z^HOMETERM^NAME field. Z^DEFINES^NAME if supplied and if Z^DEFINES^NAME^LEN is not 0, specifies the address of a string containing a set of DEFINEs to be propagated to the new process. The string must be exactly Z^DEFINES^NAME^LEN bytes long. The set of DEFINEs should have been created through one or more calls to the DEFINESAVE procedure.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Z^HEAP^MAX for native processes only, specifies the maximum size, in bytes, of the process heap. Note that the sum of the size of the heap and the size of global data cannot exceed 1.1 gigabytes (GB). The default value of 0D indicates that the heap can grow to the default value of 1.1 gigabytes (GB) less the size of the globals. The initial heap size of a process is zero bytes. For most processes, the default value is adequate.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) Valid values for Z^CREATE^OPTIONS are one or more of the following: Name (ZSYS^VAL^ ) Value Description PCreatOpt^AllDefines 16 Propagate DEFINEs in Z^DEFINES and DEFINEs in the caller’s context. In case of name conflicts, use the ones in Z^DEFINES. Otherwise, propagate DEFINEs as specified by other values.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) Z^NAME^OPTIONS specifies whether the process is to be named and, if so, whether the caller is supplying the name or the system must generate it. The following table summarizes the possible values for Z^NAME^OPTIONS. TAL literals are defined in the ZSYSTAL file. Literals in the zsysc file, for C programs, are the same as those for TAL except that they contain the underscore (_) character instead of the circumflex (^) character.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) 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^SaveAbend and PCreatOpt^RUND described in this table.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Z^CPU specifies the processor in which the new process is to run. If you specify -1, the processor is chosen as follows: Backup process: Other process on local system: Process on remote system: determined by system same processor as caller determined by system The processor number of the new process can be obtained by passing the ZSYS^DDL^SMSG^PROCCREATE.Z^PHANDLE field of the output-list parameter to the PROCESSHANDLE_DECOMPOSE_ procedure.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Structure Definition 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 as the nowait PROCESS_LAUNCH_ and PROCESS_CREATE_ completion message.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure In the C zsysc file, the structure for the output-list parameter is defined as: typedef struct __zsys_ddl_smsg_proccreate { short z_msgnumber; long z_tag; zsys_ddl_phandle_def z_phandle; short z_error; short z_error_detail; short z_procname_len; short z_reserved[4]; union { struct { signed char filler_0[50]; } z_data; char z_procname[50]; } u_z_data; } zsys_ddl_smsg_proccreate_def; Z^MSGNUMBER if it contains the returned value of -102, indicates proc
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure Z^PROCNAME^LEN for a waited request, returns the length in bytes of the process descriptor of the new process. If you created the process in a nowait manner, then the returned value is 0. You can retrieve the process descriptor length in the completion message sent to $RECEIVE. Z^PROCNAME for a waited request, returns the process descriptor of the new process.
PROCESS_LAUNCH_ Procedure Guardian Procedure Calls (P) • Program file and user library file differences A user library is an program file containing one or more procedures. The difference between a program file and a library file is that the library file cannot contain a MAIN procedure; a program file must contain a MAIN procedure. Undefined external references in a program file are resolved from the user library, if any, or the system library.
Guardian Procedure Calls (P) • PROCESS_LAUNCH_ Procedure Reserved process names The operating system reserved process name space includes the following names: $Xname, $Yname, and $Zname, where name is from 1 through 4 alphanumeric characters. You should not use names of this form in any application. Systemgenerated process names (from PROCESS_LAUNCH_, NEWPROCESS[NOWAIT], PROCESSNAME_CREATE_ , CREATEPROCESSNAME and CREATEREMOTENAME) are selected from this set of names.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure propagated; otherwise, the =_DEFAULTS DEFINE in the caller’s context is propagated. Buffer space for DEFINEs being propagated to a new process is limited to 256 KB 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.
Guardian Procedure Calls (P) PROCESS_LAUNCH_ Procedure the new process. If the caller is part of a batch job, to start a new process that is part of the caller’s batch job, set Z^JOBID to -1. • • PROCESS_LAUNCH_ 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 Z^JOBID.
Guardian Procedure Calls (P) • • • • • PROCESS_LAUNCH_ Procedure 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. Related Programming Manuals For programming information about the PROCESS_LAUNCH_ procedure, refer to the Guardian Programmer’s Guide. For programming information on batch processing, see the appropriate NetBatch manual.
Guardian Procedure Calls (P) PROCESS_SETINFO_ Procedure PROCESS_SETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESS_SETINFO_ Procedure Parameters returned value error INT returns a file-system error indicating the outcome of the operation. processhandle input INT .EXT:ref:10 is a process handle that specifies the process of interest. If this parameter is omitted or null (-1 in each word), the caller is the process of interest. input specifier INT:value indicates whether the operation should affect both members of a named process pair.
PROCESS_SETINFO_ Procedure Guardian Procedure Calls (P) input set-value-len INT:value specifies the length in words of set-value. Both set-value and set-value-len must be present unless the attribute being altered is item 40 (mom’s-processhandle). In that case, both parameters can be omitted. output old-value INT .EXT:ref:* if present and old-value-maxlen is not 0, returns the prior value of the attribute being altered.
PROCESS_SETINFO_ Procedure Guardian Procedure Calls (P) Attribute Code TAL Value Representation +* 71 propagate stop-on-logoff INT nice() caller’s value INT(32) maximum size of the main stack INT(32) 75 *104 Attributes marked with an asterisk (*) can be altered only when the caller is the target process. Attributes marked with a plus sign (+) can be altered only when the caller is a privileged process. • 40: mom's process handle sets the process handle of the mom of the specified process.
Guardian Procedure Calls (P) • PROCESS_SETINFO_ Procedure 49: qualifier information available specify 1 if the process is prepared to respond to the subordinate name inquiry system message (-107). This message is received when another process calls the FILENAME_FINDNEXT_ procedure to obtain qualifier names of the process. If the process does not respond to the message, other processes calling the FILENAME_FINDNEXT_ procedure on the system might be blocked.
Guardian Procedure Calls (P) PROCESS_SETINFO_ Procedure Considerations • The caller of PROCESS_SETINFO_ When PROCESS_SETINFO_ is called on a Guardian process, the caller 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, refer to the description under “Considerations” for the PROCESS_GETINFO_ procedure and the Guardian User’s Guide.
Guardian Procedure Calls (P) PROCESS_SETINFO_ Procedure The creator of a named process should not adopt its named child process, even if the child is a single named process rather than a named process pair. Doing so establishes the creator as its mom as well as its ancestor. When the process terminates, the creator will receive two system messages—one for the disappearance of the named process as an entity, and one for the disappearance of the adopted process.
Guardian Procedure Calls (P) • PROCESS_SETINFO_ Procedure Primary If a switch or a backup takeover occurs (causing the backup process to become the new primary) through use of the checkpoint procedures, it is not necessary to use PROCESS_SETINFO_ to set the primary attribute of the new primary. The checkpoint procedures automatically identify the new primary process to the operating system.
PROCESS_SETINFO_ Procedure Guardian Procedure Calls (P) Figure 12-1. Effect of Adopting a Process (A) Creates (B) : (A) (B) MOM = (A) (B) Creates (C) : (A) (B) (C) MOM = (A) MOM = (B) (C) calls PROCESS_SETINFO_ with item 40 and passes B's process ID (A) (B) (C) MOM = (C) MOM = (B) (B) receives a process deletion message if (C) is deleted. Likewise, (C) receives a process deletion message if (B) is deleted. VST003.
Guardian Procedure Calls (P) PROCESS_SETSTRINGINFO_ Procedure PROCESS_SETSTRINGINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Considerations 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.
Guardian Procedure Calls (P) PROCESS_SETSTRINGINFO_ Procedure Syntax for TAL Programmers error := PROCESS_SETSTRINGINFO_ ( [ processhandle ] ,[ specifier ] ,set-attr-code ,set-value:length i:i ,[ old-value:maxlen ] o:i ,[ old-value-len ] ); ! i ! i ! i ! ! ! o Parameters returned value error INT returns a file-system error number indicating the outcome of the operation. processhandle input INT .EXT:ref:10 is a process handle that specifies the process of interest.
Guardian Procedure Calls (P) PROCESS_SETSTRINGINFO_ Procedure set-value:length input:input STRING .EXT:ref:*, INT:value is the new value for the attribute to be altered. The value of set-value must be exactly length bytes long. old-value:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns the prior value for the attribute being altered. old-value-len output INT .EXT:ref:1 is the actual length in bytes of old-value.
Guardian Procedure Calls (P) • PROCESS_SETSTRINGINFO_ Procedure home terminal This is the only attribute that currently can be altered by PROCESS_SETSTRINGINFO_. If a process alters this attribute, the new home terminal becomes the home terminal for any process that it subsequently creates.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure PROCESS_SPAWN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Structure Definition for fdinfo Structure Definition for inheritance Structure Definition for process-extension Structure Definition for process-results Nowait 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 Pro
Guardian Procedure Calls (P) • • • • • • • • • PROCESS_SPAWN_ Procedure You can call PROCESS_SPAWN_ from either a Guardian process or an OSS process. The caller of PROCESS_SPAWN_ becomes the Guardian parent of the new OSS process. Because the caller of PROCESS_SPAWN_ is the Guardian parent of the new OSS process, when the new process is terminated, it receives a process deletion system message (-101) through its $RECEIVE file rather than an OSS SIGCHLD signal.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Syntax for C Programmers #include __int32_t PROCESS_SPAWN_ ( [ char *oss-program-file ] ,[ void *fdinfo ] ,[ char *argv ] ,[ char *envp ] ,[ void *inheritance ] ,[ __int32_t inheritance-length ] ,[ void *process-extension ] ,[ void *process-results ] ,[ __int32_t nowait-tag ] ,[ char *path ] ); • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t which for TNS and TNS/R compiles is d
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure oss-program-file input STRING .EXT:ref:* specifies the null-terminated OSS pathname of the OSS program file to be run. If the pathname is an absolute pathname, it is resolved relative to the root of the caller. If the pathname is a relative pathname, it is resolved with respect to the caller’s current working directory. If the pathname is the program name, the path provided in the path parameter is searched for the program file.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure includes the pointers and the null terminators on the strings, is available by calling the OSS sysconf(_SC_ARG_MAX) function. input envp EXTADDR .EXT:ref:1 if present and not equal to 0D, specifies the address of an array of addresses that point to null-terminated strings that describe the environment of the new process. The last member of this array must be a null pointer (0D).
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure functions. The list of _TPC_ macros described in this reference page is not complete; for a current description of error macros and error codes, see the Guardian header file $SYSTEM.ZSPIDEF.ZGRDC or Table 12-3, Summary of Process Creation Errors . nowait-tag input INT(32):value if present and not equal to -1D, indicates that the process is to be created in a nowait manner; the PROCESS_SPAWN_ procedure returns as soon as process creation is initiated.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) Structure Definition for fdinfo The fdinfo parameter specifies the file descriptors to be opened or duplicated by the new process. The structure for the fdinfo parameter can contain multiple occurrences of the Z^FDENTRY substructure (fdentry for C programs).
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure In the C tdmext.h header file, the structures for the fdinfo parameter are defined as: typedef struct fdinfo { long z_len; long z_timeout; long z_umask; char *z_cwd; long z_fdcount; fdentry_def z_fdentry; } fdinfo_def; typedef struct fdentry { long z_fd; long z_dupfd; char *z_name; long z_oflag; long z_mode; } fdentry_def; C programs should initialize the fdinfo structure by using the #define DEFAULT_FDINFO in the tdmext.h header file.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure 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 should be used. For more information refer to 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.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) Z^Name is the address of a string containing the null-terminated OSS pathname of the file to be opened by the new process. It must be possible to open this file with the OSS open() function. A relative pathname is resolved with the value for the OSS current working directory in Z^CWD. To have the new process open a pipe, specify a named pipe (also known as a FIFO) in the Z^NAME field. To create a FIFO, use the OSS mkfifo() function.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) Corresponding open() Flag Name (ZSYS^VAL^ ) Value Description OSSOPEN^NONBLOC K 1638 4 Open for nonblocked access O_NONBLOCK OSSOPEN^SYNC 6553 6 Open for synchronized update O_SYNC OSSOPEN^TRUNC 16 Open and empty the file O_TRUNC Z^MODE is the read, write, and execute permissions of the file to be created when Z^OFLAG is set to ZSYS^VAL^OSSOPEN^CREAT. Otherwise, Z^MODE is ignored.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) 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 sho
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Structure Definition for process-extension The process-extension parameter specifies the Guardian attributes of the new process.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) For TAL programs, the following default values must be specified when an option is not wanted: Field Name Default Value Z^LEN $OFFSET (ZSYS^DDL^PROCESSEXTENSION.Z^OSSOPTIONS) + $LEN (ZSYS^DDL^PROCESSEXTENSION.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure In the C tdmext.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure If you specify the default value 0D, the process uses the same user library file (if any) as it did the last time it was run (or with no file if that was how it was run) or with the library file currently executing. Write permission to the program file is not required. Refer to the Binder Manual for more information about TNS user libraries. Refer to the nld and noft Manual for more information about native user libraries and shared run-time libraries.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) For native processes, this parameter is ignored because TNS/R native processes do not need an extended swap file. The default value is 0D. See ”Considerations for Resolving File Names” and “DEFINE Considerations” for more information about the swap files. Z^Priority is the initial execution priority to be assigned to the new process. Execution priority is a value in the range 1 through 199, where 199 is the highest possible priority.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Z^ProcessName is the address of a null-terminated string that specifies the name to be assigned to the new process. The name cannot include a node name. This parameter is relevant only when Z^NAMEOPTIONS has the value ZSYS^VAL^PCREATOPT^NAMEINCALL. See the considerations later in this subsection and Appendix B, Reserved Process Names, for information about reserved process names.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) except that they contain the underscore (_) character instead of the circumflex (^) character. Valid values for Z^CREATEOPTIONS are one or more of the following: Name (ZSYS^VAL^ ) Value Description PCreatOpt^AllDefines 16 Propagate DEFINEs in Z^DEFINES and DEFINEs in the caller’s context. In case of name conflicts, use the ones in Z^DEFINES. Otherwise, propagate DEFINEs as specified by other values.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Z^Defines is the address of a null-terminated string that specifies a set of DEFINEs to be propagated to the new process. The value of Z^DEFINES must be exactly Z^DEFINESLEN bytes long. The set of DEFINEs should have been created through one or more calls to the DEFINESAVE procedure. DEFINEs are propagated according to the values specified in Z^CREATEOPTIONS. See “DEFINE Considerations” for details. The default value is 0D.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) Valid values for Z^DebugOptions are as follows: Name (ZSYS^VAL^ ) Value Description PCreatOpt^DbgOverrid e 2 PCreatOpt^Default 0 Use 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 ZSYS^VAL^PCREATOPT^SAVEABEND and ZSYS^VAL^PCREATOPT^RUND described in this table.
PROCESS_SPAWN_ Procedure Guardian Procedure Calls (P) Z^OSSOptions 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 indicates that the main stack can grow to 1MB. For most processes, the default value is adequate.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Structure Definition for process-results The process-results parameter provides Guardian information on the outcome of the PROCESS_SPAWN_ procedure call.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure C programs should 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.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Z^ERRNO Description 4014 A specified parameter has an invalid address. The corresponding OSS errno value is EFAULT. 4020 A prefix within a pathname refers to a file other than a directory. The corresponding OSS errno value is ENOTDIR. 4022 Either a parameter in the parameter list is invalid or a required parameter is omitted. The corresponding OSS errno value is EINVAL. 4126 Operation timed out.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure 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.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure An I/O error to the home terminal can occur if there are undefined externals in the program file and PROCESS_SPAWN_ is unable to open or write to the home terminal to display the undefined externals messages. The Z^TPCDETAIL field of the process-results parameter contains the file-system error number that resulted from the open or write that failed.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure 3. The caller process receives the processor down message from processor 6. At this point, the caller process does not know whether its OSS child process still exists, because the child process could have migrated from processor 2 to processor 6. The caller process calls PROCESS_GETINFOLIST_ with the OSS process ID of the child process. PROCESS_GETINFOLIST_ returns error 4 indicating that the specified process does not exist. 4.
Guardian Procedure Calls (P) PROCESS_SPAWN_ Procedure Buffer space for DEFINEs being propagated to a new process is limited to 256 KB 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.
Guardian Procedure Calls (P) • • PROCESS_SPAWN_ Procedure PROCESS_SPAWN_ 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 Z^JOBID. PROCESS_SPAWN_ can create a new batch job and establish the new process as a member of the newly created batch job.
PROCESS_STOP_ Procedure Guardian Procedure Calls (P) PROCESS_STOP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations NetBatch Considerations Safeguard Considerations OSS Considerations Examples Related Programming Manual Summary The PROCESS_STOP_ procedure deletes a process or process pair.
PROCESS_STOP_ Procedure Guardian Procedure Calls (P) Syntax for TAL Programmers error := PROCESS_STOP_ [ ( [ ,[ ,[ ,[ ,[ ,[ ,[ processhandle ] specifier ] options ] completion-code ] termination-info ] spi-ssid ] text:length ] ) ]; ! ! ! ! ! ! ! i i i i i i i:i Parameters returned value error INT unless the caller successfully stops itself, returns a file-system error number that indicates the outcome of the operation.
PROCESS_STOP_ Procedure Guardian Procedure Calls (P) input options INT:value specifies whether the process is being stopped because of a normal or abnormal condition. Valid values are: Reserved (specify 0) <0:14> 0 1 <15> Normal termination (STOP) Abnormal termination (ABEND) The default is 0.
Guardian Procedure Calls (P) PROCESS_STOP_ Procedure input:input text:length STRING .EXT:ref:*, INT:value if present and length is not 0, is a string of ASCII text to be sent as part of the process deletion system message. If used, the value of text must be exactly length bytes long. The maximum length is 80 bytes. Considerations • • When PROCESS_STOP_ executes, all open files associated with the deleted process are closed. If a process had BREAK enabled, BREAK is disabled.
Guardian Procedure Calls (P) PROCESS_STOP_ Procedure receive either C-format messages or D-format messages. Refer to the description of the FILE_OPEN_ procedure for details.) PROCESS_STOP_ sends a default completion code of 0 when the STOP option is specified; it sends a completion code of 5 when the ABEND option is specified.
Guardian Procedure Calls (P) PROCESS_STOP_ Procedure reference page either online or in the Open System Services System Calls Reference Manual. • Rules for stopping any process: stop mode When a process tries to stop another process, another item checked is the stop mode of that process. The stop mode is a value associated with every process that determines what other processes can stop it. The stop mode, set by the SETSTOP procedure, is defined as follows: 0 1 2 Any other process can stop the process.
Guardian Procedure Calls (P) • • • PROCESS_STOP_ Procedure If a process calls PROCESS_STOP_ on another process, the system supplies a completion code value of 6. If a process calls PROCESS_STOP_ with the STOP option on itself but does not supply a completion code, the system supplies a completion code value of 0. If a process calls PROCESS_STOP_ with the ABEND option on itself but does not supply a completion code, the system supplies a completion code value of 5.
Guardian Procedure Calls (P) • • PROCESS_STOP_ Procedure The pid parameter set to the OSS process ID of the process identified by processhandle in the PROCESS_STOP_ call The security rules that apply to stopping an OSS process using PROCESS_STOP_ are the same as those that apply to the OSS kill() function. See the kill(2) function reference page either online or in the Open System Services System Calls Reference Manual for details. Examples INT stop^option; . .
Guardian Procedure Calls (P) PROCESS_SUSPEND_ Procedure PROCESS_SUSPEND_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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).
Guardian Procedure Calls (P) PROCESS_SUSPEND_ Procedure processhandle input INT .EXT:ref:10 specifies the process handle of the process to be suspended. input specifier INT:value for a named process pair, indicates whether both members should be suspended. Valid values are: 0 Suspend the specified process only. 1 Suspend both members of current instance of named process pair if the specified process is part of a named process pair; otherwise suspend the specified process. The default is 0.
Guardian Procedure Calls (P) PROCESS_WAIT_ When PROCESS_SUSPEND_ is called on an OSS process, the security rules that apply are the same as those that apply when calling the OSS kill() function. See the kill(2) function reference page either online or in the Open System Services System Calls Reference Manual for details. Safeguard Considerations For information on processes protected by Safeguard, refer to the Safeguard Reference Manual.
Guardian Procedure Calls (P) PROCESSACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ PROCESSACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ 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. The PROCESSACCESSID procedure is used to obtain the process access ID (PAID) of the calling process.
Guardian Procedure Calls (P) PROCESSACCESSID Procedure (Superseded by PROCESS_GETINFOLIST_ The process access ID (PAID) is returned from the PROCESSACCESSID procedure and is normally used for security checks when a process attempts to access a disk file. The creator access ID (CAID) is returned from the CREATORACCESSID and identifies the user who created the process.
Guardian Procedure Calls (P) PROCESSFILESECURITY Procedure (Superseded by PROCESS_SETINFO_ Procedure PROCESSFILESECURITY Procedure (Superseded by PROCESS_SETINFO_ Procedure or PROCESS_GETINFOLIST_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
Guardian Procedure Calls (P) PROCESSFILESECURITY Procedure (Superseded by PROCESS_SETINFO_ Procedure <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 the following: 0 1 2 4 5 6 7 Any user (local) Member of owner’s group (local) Owner (local) Any user (local or remote) Member of owner’s community (local or remote) Owner (local or remote) Super ID only (local) If security is omitted, PROCESSFILESECURITY returns the current security
Guardian Procedure Calls (P) PROCESSHANDLE_COMPARE_ Procedure PROCESSHANDLE_COMPARE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESSHANDLE_COMPARE_ Procedure processhandle-2 input INT .EXT:ref:10 is the other process handle to be compared. 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.
Guardian Procedure Calls (P) PROCESSHANDLE_DECOMPOSE_ Procedure PROCESSHANDLE_DECOMPOSE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The PROCESSHANDLE_DECOMPOSE_ procedure returns one or more parts of a process handle. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (P) PROCESSHANDLE_DECOMPOSE_ Procedure Syntax for TAL Programmers error := PROCESSHANDLE_DECOMPOSE_ ( processhandle i ,[ cpu ] o ,[ pin ] o ,[ nodenumber ] o ,[ nodename:maxlen o:i ,[ nodename-length o ,[ procname:maxlen o:i ,[ procname-length o ,[ sequence-number o ! ! ! ! ] ! ] ! ] ! ] ! ] ); ! Parameters returned value error INT is a file-system error number indicating the outcome of the operation. processhandle input INT .
Guardian Procedure Calls (P) PROCESSHANDLE_DECOMPOSE_ Procedure output nodenumber 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 .EXT:ref:*, INT:value if present, returns the name of the node in which the process designated by processhandle resides. maxlen is the length in bytes of the string buffer nodename. output nodename-length INT .
Guardian Procedure Calls (P) PROCESSHANDLE_DECOMPOSE_ Procedure Related Programming Manual For programming information about the PROCESSHANDLE_DECOMPOSE_ procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (P) PROCESSHANDLE_GETMINE_ Procedure PROCESSHANDLE_GETMINE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (P) PROCESSHANDLE_NULLIT_ Procedure PROCESSHANDLE_NULLIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. Refer to Appendix D, File Names and Process Identifiers for further information about process handles.
Guardian Procedure Calls (P) PROCESSHANDLE_TO_CRTPID_ Procedure PROCESSHANDLE_TO_CRTPID_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The PROCESSHANDLE_TO_CRTPID_ procedure converts a process handle to the corresponding process ID (CRTPID). Refer to Appendix D, File Names and Process Identifiers for a description of process IDs.
Guardian Procedure Calls (P) PROCESSHANDLE_TO_CRTPID_ Procedure output process-id INT .EXT:ref:4 returns the process ID (CRTPID) of the process designated by processhandle. If the process is named and local to the node indicated by node-number, the process ID is in local form. In all other cases the process ID is in network form. input pair-flag INT:value specifies whether process-id should designate a process pair (1 if it should; 0 if it should not).
Guardian Procedure Calls (P) PROCESSHANDLE_TO_FILENAME_ Procedure PROCESSHANDLE_TO_FILENAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The PROCESSHANDLE_TO_FILENAME_ procedure converts a process handle to a process file name.
Guardian Procedure Calls (P) PROCESSHANDLE_TO_FILENAME_ Procedure input processhandle INT .EXT:ref:10 is the process handle to be converted. If a null process handle (-1 in each word) is specified, the process handle of the calling process is used. filename:maxlen output:input STRING .EXT:ref:*, INT:value returns the process file name of the process designated by processhandle. filename includes the node name of the process; it does not include qualifiers.
Guardian Procedure Calls (P) PROCESSHANDLE_TO_STRING_ Procedure PROCESSHANDLE_TO_STRING_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The PROCESSHANDLE_TO_STRING_ procedure converts a process handle to the equivalent process string. See “Considerations,” below, for a description of process strings.
Guardian Procedure Calls (P) PROCESSHANDLE_TO_STRING_ Procedure processhandle input INT .EXT:ref:10 is the process handle to be converted. process-string:maxlen output:input STRING .EXT:ref:*, INT:value returns a process string that represents the process designated by processhandle. The node name is included in process-string, except as described under node. maxlen is the length in bytes of the string variable process-string. process-string-length output INT .
Guardian Procedure Calls (P) PROCESSHANDLE_TO_STRING_ Procedure Considerations • A process string is a string of characters that identifies a process or a set of processes. Process strings are commonly used in command lines (for example, in the TACL STATUS command). PROCESSHANDLE_TO_STRING_ returns a process string in one of the following forms: [\node.]cpu,pin [\node.]$process-name • • If you request the process name for a named process, PROCESSHANDLE_TO_STRING_ looks up the process by name.
Guardian Procedure Calls (P) PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ 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. The PROCESSINFO procedure is used to obtain process status information.
Guardian Procedure Calls (P) PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ Parameters returned value error INT returns a value indicating the 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 4-word process ID of the process for which status is being returned is returned, in the process-id parameter (if present).
PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ Guardian Procedure Calls (P) Note that process ID is a 4-word array where: Process name or creation timestamp [0:2] [3].<0:3> .<4:7> Reserved Processor number where the process is executing .<8:15> PIN assigned by the operating system to identify the process in the processor. creator-access-id input, output INT:ref:1 returns the creator access ID of process-id.
Guardian Procedure Calls (P) PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ input, output home-terminal 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). input sysnum INT:value specifies the system (in a network) where the process for which information is to be returned is running.
Guardian Procedure Calls (P) PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ output priv-only INT:ref:* This parameter can be used only by a privileged caller. process-time output FIXED:ref:1 returns the process time, in microseconds, for which the process has executed. output wait-state 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’s process control block.
PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ Guardian Procedure Calls (P) 4 5 6 7 8 9 10 11 12 13 14 Debug memory access breakpoint Debug breakpoint Debug trap or signal Debug request Inspect memory access breakpoint Inspect breakpoint Inspect trap or signal Inspect request saveabend terminating XIO initialization library-filename output INT:ref:12 returns the internal-format file name of the library file used by the process.
Guardian Procedure Calls (P) PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ output licenses INT:ref:1 licenses.<15> returns 0 if the program file of the process was not licensed at process-creation time, and returns 1 if the program file of the process was licensed at process-creation time. input, output jobid INT:ref:5 consists of the GMOM’s process ID plus the jobid. If this field is zero, the process does not belong to a job.
Guardian Procedure Calls (P) • PROCESSINFO Procedure (Superseded by PROCESS_GETINFOLIST_ High-PIN processes You cannot use PROCESSINFO on high-PIN processes, because a high PIN cannot fit into cpu,pin or process-id.
Guardian Procedure Calls (P) PROCESSNAME_CREATE_ Procedure PROCESSNAME_CREATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) PROCESSNAME_CREATE_ Procedure Parameters returned value error INT indicates the outcome of the operation. It returns one of the following file-system errors: 0 44 201 590 Process name is returned successfully. No names of the specified type are available. Unable to communicate with the specified node. Parameter or bounds error. output:input name:maxlen STRING .EXT:ref:*, INT:value returns the process name. maxlen is the length in bytes of the string variable name.
PROCESSNAME_CREATE_ Procedure Guardian Procedure Calls (P) input:input nodename:length STRING .EXT:ref:*, INT:value if supplied and if length is not 0, specifies the node name that is to be returned as part of the process name if a node name is desired, as indicated by the options parameter. If used, the value of nodename must be exactly length bytes long. If this parameter is omitted or if length is 0, and if options.<15> = 0 (node name is desired), the name of the caller’s node is used.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure PROCESSOR_GETINFOLIST_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Attribute Codes and Value Representations 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.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure Parameters returned value error INT indicates the outcome of the operation. It returns one of the following values: Description error 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.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure ret-attr-count input INT:value indicates how many items the caller is supplying in ret-attr-list. If the return values cannot fit into ret-values-list, the procedure returns an error of 1 and an error-detail value of 563 (buffer too small). No processor information is returned. ret-values-list output INT .EXT:ref:* contains ret-values-len words of returned information. The values parallel the items in ret-attr-list.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure General Considerations • If PROCESSOR_GETINFOLIST_ returns a nonzero error value, the contents of ret-values-list and ret-values-len are undefined.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure Code Attribute TAL Value Representation 27 process time list elements INT number of elements, INT(32) ARRAY 28 breakpoints INT 29 send busy FIXED 35 interrupt count INT number of elements, INT(32) ARRAY 36 disk cache hits FIXED 37 disk I/Os FIXED 38 processor queue state INT, INT, FIXED 39 memory queue state INT, INT, FIXED 40 sequenced sends unsigned INT(32) 41 unsequenced sends unsigned INT(32) 42 CME events
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure If PROCESSOR_GETINFOLIST_ cannot obtain meaningful data for an attribute that returns an array, it returns a value of 0 for the number of array elements and allocates no space for the actual array. Except where otherwise noted, PROCESSOR_GETINFOLIST_ returns a value of -1 (for an INT), -1D (for an INT(32)), or -1F (for a FIXED) when it cannot obtain a meaningful value for an attribute that does not return an array.
Guardian Procedure Calls (P) • PROCESSOR_GETINFOLIST_ Procedure 10: maximum locked memory the maximum amount of virtual memory, in pages, that can be locked in physical memory. If the number of pages exceeds 2,147,483,647 (2**31 - 1), the returned value is -1D. • 11: high locked memory the maximum amount of virtual memory, in pages, that has been locked in physical memory at any one time since the processor was loaded. If the number of pages exceeds 2,147,483,647 (2**31 - 1), the returned value is -1D.
Guardian Procedure Calls (P) • PROCESSOR_GETINFOLIST_ Procedure 20: idle time the amount of time, in microseconds, that has not been spent in process execution or interrupt handling since the processor was loaded. • 21: interrupt time the amount of time, in microseconds, that has been spent handling interrupts since the processor was loaded. • 22: processor queue length the current number of processes that are ready to execute. The returned value is an unsigned integer.
Guardian Procedure Calls (P) • PROCESSOR_GETINFOLIST_ Procedure 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.
Guardian Procedure Calls (P) • PROCESSOR_GETINFOLIST_ Procedure 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.
Guardian Procedure Calls (P) • PROCESSOR_GETINFOLIST_ Procedure 45: interpreter transitions for NSR-L processors, the number of times that accelerated code has entered the interpreter since the Measure product started collecting statistics on the processor. If the processor is not a NSR-L processor, 0D is returned. • 46: transactions the number of transactions since the Measure product started collecting statistics on the processor.
PROCESSOR_GETINFOLIST_ Procedure Guardian Procedure Calls (P) • 56: base time the timestamp of when the processor was loaded. See the TIMESTAMP procedure for a description of this form of the timestamp. The base time is set to 1F when the processor of interest is running a RVU earlier than D30. • 57: memory-management attributes the memory-management attributes of the processor.
Guardian Procedure Calls (P) PROCESSOR_GETINFOLIST_ Procedure Example In the following 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_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-6.
PROCESSOR_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-6.
PROCESSOR_GETINFOLIST_ Procedure Guardian Procedure Calls (P) Table 12-6.
Guardian Procedure Calls (P) PROCESSOR_GETNAME_ Procedure PROCESSOR_GETNAME_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 numerical representation of the processor type.
Guardian Procedure Calls (P) PROCESSOR_GETNAME_ Procedure Syntax for TAL Programmers error := PROCESSOR_GETNAME_ ( [ cpu-number ] ,name:maxlen ,namelen ,[ cpu-type-out ] ,[ node-name:length ] ,[ node-number ] ,[ cpu-type-in ] ,[ expand-name ] ,[ cpu-model-out ] ,[ cpu-model-in ] ); ! ! ! ! ! ! ! ! ! ! i o:i o o i:i i i i o i Parameters returned value error INT returns a file-system error number indicating the outcome of the operation.
PROCESSOR_GETNAME_ Procedure Guardian Procedure Calls (P) Possible return values for name are: Processor Type name 0 “NonStop 1+” 1 “NonStop II” 2 “TXP” 3 “VLX” 4 “NSR-L” or “CLX” 5 “Cyclone” 6 “NSR-L” 7 “NSR-N” “NSR-P” “NSR-K” 8 “NSR-W” 9 “NSR-D” 9 “NSR-E” 9 “NSR-G” 9 “NSR-H” 9 “NSR-J” 9 "NSR-T" 9 “NSR-V” 9 “NSR-X” 9 “NSR-Y” 9 “NSR-Z” 10 “NSE-A” otherwise maxlen blanks Processor types 0, 1, 2, 3, 4, and 5 are no longer supported. output namelen INT .
Guardian Procedure Calls (P) PROCESSOR_GETNAME_ Procedure “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. The value of node-name must be exactly length bytes long. If this parameter is omitted or if length is 0, and if nodenumber does not specify a node, the local node is used.
Guardian Procedure Calls (P) PROCESSOR_GETNAME_ Procedure Considerations If you supply more information than is necessary to identify the processor or the processor type of interest (that is, if you specify both node-number and node-name, or if you identify the processor and also specify cpu-type-in), PROCESSOR_GETNAME_ uses the first sufficient set of parameters that it encounters and ignores the rest.
Guardian Procedure Calls (P) PROCESSORSTATUS Procedure PROCESSORSTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. See Table 12-6, Summary of Processor Types and Models for further information about supported processors.
PROCESSORSTATUS Procedure Guardian Procedure Calls (P) The least significant word is a bit mask indicating the operational state of each processor module: most significant word, highest processor number + 1 Word[0] least significant word, bit mask 1 or 0 [1] ls word.<0> ls word.<1> . . . ls word.<14> ls word.<15> = = processor module 0 processor module 1 = = processor module 14 processor module 15 For each bit: 1 up 0 down indicates that the corresponding processor module is up (operational).
Guardian Procedure Calls (P) PROCESSORTYPE Procedure PROCESSORTYPE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary The PROCESSORTYPE procedure returns the processor type of a specified system and processor. See Table 12-6, Summary of Processor Types and Models for further information about supported processors.
Guardian Procedure Calls (P) PROCESSORTYPE Procedure 9 HP NonStop NSR-D processor HP NonStop NSR-E processor HP NonStop NSR-G processor HP NonStop NSR-H processor HP NonStop NSR-J processor HP NonStop NSR-T processor HP NonStop NSR-V processor HP NonStop NSR-X processor HP NonStop NSR-Y processor HP NonStop NSR-Z processor 10 HP NonStop NSE-A processor If cpu is greater than 16 or less than 0, then -1 is returned. If sysid is invalid or the system is unavailable across the network, then -1 is returned.
Guardian Procedure Calls (P) PROCESSSTRING_SCAN_ Procedure PROCESSSTRING_SCAN_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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” for the definition of process string.
Guardian Procedure Calls (P) PROCESSSTRING_SCAN_ Procedure Parameters returned value error INT is a file-system error number indicating the outcome of the operation. string:length input:input STRING .EXT:ref:*, INT:value is a character string to be searched to find a valid process string. string must be exactly length bytes long. A valid process string must begin at the first character of string.
PROCESSSTRING_SCAN_ Procedure Guardian Procedure Calls (P) output:input name:maxlen STRING .EXT:ref:*, INT:value if present, returns the name of a node or process. If stringtype is less than 3, name returns the node name that was contained in the process string (if no node name was specified, the returned value of namelen is 0). If stringtype is 3, the returned value is the specified process name, including the node name, if present. maxlen is the length in bytes of the string variable name.
Guardian Procedure Calls (P) PROCESSSTRING_SCAN_ Procedure Considerations • A process string is a string of characters that identifies a process or a set of processes. Process strings are commonly used in command lines (for example, in the TACL STATUS command). PROCESSSTRING_SCAN_ accepts process strings in the following forms: [\node.]cpu,pin [\node.]cpu [\node.]$process-name [\node.]* • If you request the processhandle, PROCESSSTRING_SCAN_ verifies that the process exists.
Guardian Procedure Calls (P) PROCESSTIME Procedure (Superseded by PROCESS_GETINFOLIST_ PROCESSTIME Procedure (Superseded by PROCESS_GETINFOLIST_ 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. The PROCESSTIME procedure returns the process execution time of any process in the network.
Guardian Procedure Calls (P) PROCESSTIME Procedure (Superseded by PROCESS_GETINFOLIST_ input cpu,pin INT:value is the processor (in bits <4:7> with <0:3> not used) and PIN (in bits <8:15>) number of the process whose execution time is to be returned. If cpu,pin is omitted, the cpu,pin of the current process (calling process) is used, even if sysid is different than the current system. input sysid INT:value is the system number. sysid defaults to the current system.
Guardian Procedure Calls (P) PROGRAMFILENAME Procedure (Superseded by PROCESS_GETINFOLIST_ PROGRAMFILENAME Procedure (Superseded by PROCESS_GETINFOLIST_ Procedure) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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’s program file.
Guardian Procedure Calls (P) PURGE Procedure (Superseded by FILE_PURGE_ Procedure ) PURGE Procedure (Superseded by FILE_PURGE_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (P) [8:11] PURGE Procedure (Superseded by FILE_PURGE_ Procedure ) file-id (blank-fill) Temporary Disk File [0:3] $volname (blank-fill) or \sysnum volname (blank-fill) [4:11] #temporary-file-id 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 filesystem errors 52, 54, 58), the file is purged, and an error returns.
Guardian Procedure Calls (P) • PURGE Procedure (Superseded by FILE_PURGE_ Procedure ) Expiration dates PURGE checks the expiration date of a file before it purges the file. If the expiration date is later than the current date, PURGE does not purge the file and returns error code 1091. Safeguard Considerations For information on files protected by Safeguard, refer to the Safeguard Reference Manual. OSS Considerations This procedure operates only on Guardian objects.
PUTPOOL Procedure (Superseded by POOL_* Procedures) Guardian Procedure Calls (P) PUTPOOL Procedure (Superseded by POOL_* Procedures) BOOKMARK 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. *POOL procedures are replaced by POOL_* procedures. There is no one-for-one replacement.
Guardian Procedure Calls (P) PUTPOOL Procedure (Superseded by POOL_* Procedures) input pool-block STRING .EXT:ref:* is the address of the block to be returned to the pool. Condition Code Settings < (CCL) indicates that the data structures are invalid or that pool-block is not a block in the buffer pool. = (CCE) indicates that the operation is successful. > (CCG) is not returned from PUTPOOL. Considerations GETPOOL and PUTPOOL do not check pool data structures on each call.
13 Guardian Procedure Calls (R) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter R. Table 13-1 lists all the procedures in this section. Table 13-1.
Guardian Procedure Calls (R) RAISE_ Procedure RAISE_ Procedure Note. This procedure can be called only from native processes. RAISE_ 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 Guardian Procedure Calls (R) READ[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Errors for READX Only Example Related Programming Manuals Summary The READ[X] procedures return data from an open file to the application process’s data area. READ is intended for use with 16-bit addresses, while READX is intended for use with 32-bit extended addresses.
READ[X] Procedures Guardian Procedure Calls (R) • 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). Syntax for TAL Programmers CALL READ[X] ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters input filenum INT:value (Use with both READ and READX) is the number of an open file that identifies the file to be read.
Guardian Procedure Calls (R) READ[X] Procedures input tag INT(32):value (Use with both READ and READX) 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.
Guardian Procedure Calls (R) • READ[X] Procedures Nowait READ[X] If a nowait READ[X] is executed, count-read has no meaning and can be omitted. The count of the number of bytes read is obtained through the counttransferred parameter of the AWAITIO[X] procedures when the I/O operation completes. The READ[X] procedure must complete with a call to the AWAITIO[X] procedure when it is used with a file that is opened nowait. If READX is used, you must call AWAITIOX to complete the I/O.
Guardian Procedure Calls (R) • • • • • • • • • • • READ[X] Procedures The buffer address and count-transferred address must be relative; they cannot be an absolute extended address. If buffer or count-transferred is in a selectable extended data segment, the segment must be in use at the time of the call. Flat segments allocated by a process are always accessible to the process. The size of the transfer is subject to current restrictions for the type of file.
Guardian Procedure Calls (R) READ[X] Procedures Disk File Considerations • Large data transfers for unstructured files using default mode For the read procedures (READ[UPDATE] [LOCK] [X]), using default mode allows I/O sizes for unstructured files to be as large as 56 kilobytes (57,344), if the unstructured buffer size is 4 KB (4096). Default mode here refers to the mode of the file if SETMODE function 141 is not invoked.
READ[X] Procedures Guardian Procedure Calls (R) • reading of an exact subset of records If an exact subset is being read, the only records returned are those whose key field, as designated by the current-key specifier, contains a value of exactly the comparison length bytes (see the KEYPOSITION procedure) and is equal to the key. When the current key no longer matches, an EOF indication returns. The exact subset for a key field having a unique value is at most one record.
Guardian Procedure Calls (R) READ[X] Procedures 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. However, there is a performance penalty if the READ[X] does not start on a BUFFERSIZE boundary and does not have a read-count that is an integral multiple of the BUFFERSIZE.
READ^FILE Procedure Guardian Procedure Calls (R) READ^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (R) READ^FILE Procedure 6 System message (only if user requested system messages through SET^SYSTEMMESSAGES or SET^SYSTEMMESSAGESMANY) 111 Operation aborted because of BREAK (if BREAK is enabled). If nowait is not zero, and if abort-on-error is in effect, the only possible value for error is 0. input file-fcb INT:ref:* identifies the file to be read. output buffer INT:ref:* is where the data is returned. The buffer must be located within ‘G’[ 0:32767 ] process data area.
Guardian Procedure Calls (R) READ^FILE Procedure Considerations • Terminal or Process File If the file is a terminal or process, a WRITEREAD operation is performed using the interactive prompt character or prompt-count character from buffer. For $RECEIVE, READ^FILE does a READUPDATE instead of a READ. Example ERROR := READ^FILE ( IN^FILE , BUFFER , COUNT ); Related Programming Manual For programming information about the READ^FILE procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (R) READEDIT Procedure READEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
READEDIT Procedure Guardian Procedure Calls (R) 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.
Guardian Procedure Calls (R) READEDIT Procedure 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.
Guardian Procedure Calls (R) READEDIT Procedure unpacked-length output INT .EXT:ref:1 returns the actual length in bytes of the value returned in unpacked-line. If unpacked-line is not large enough to contain the value that is the output of the operation, unpacked-length returns a negative value. [ reserved parameter ] is reserved for internal use. When using the parameters that follow, you must supply a placeholder comma for the reserved parameter.
Guardian Procedure Calls (R) READEDITP Procedure READEDITP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_. Syntax for C Programmers Note.
READEDITP Procedure Guardian Procedure Calls (R) input filenum INT:value specifies the file number of the open file that is to be read. input, output record-number 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, READEDITP 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.
Guardian Procedure Calls (R) READEDITP Procedure Example error := READEDITP ( filenumber, record^num, line^image, line^maxlength, line^actual^length ); 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 READEDITP procedure, refer to the Guardian Programmer’s Guide.
READLOCK[X] Procedures Guardian Procedure Calls (R) READLOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Errors for READLOCKX Only Considerations for READLOCKX Only OSS Considerations Related Programming Manuals Summary The READLOCK and READLOCKX procedures sequentially lock and read records in a disk file, exactly like the combination of LOCKREC and READ[X].
READLOCK[X] Procedures Guardian Procedure Calls (R) Syntax for TAL Programmers CALL READLOCK[X] ( filenum ,buffer ,read-count ,[ count-read ] ,[ tag ] ); ! ! ! ! ! i o i o i Parameters input filenum INT:value (Use with both READLOCK and READLOCKX) is the number of an open file that identifies the file to be read. output buffer INT:ref:* (Use with READLOCK) STRING .EXT:ref:* (Use with READLOCKX) is an array in the application process where the information read from the file returns.
Guardian Procedure Calls (R) READLOCK[X] Procedures Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). < (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 the following record along that path.
Guardian Procedure Calls (R) READLOCK[X] Procedures pointer is set to the previous next-record pointer plus read-count. This process repeats for each subsequent call to READLOCK[X]. • See “Considerations” for the READ procedure. Considerations for READLOCKX Only • • • • • • • • • • The buffer and count transferred may be in the user stack or in an extended data segment. The buffer and count transferred cannot be in the user code space.
Guardian Procedure Calls (R) • • READLOCK[X] Procedures 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. OSS Considerations • This procedure operates only on Guardian objects. If an OSS file is specified, error 2 is returned.
Guardian Procedure Calls (R) READUPDATE[X] Procedures READUPDATE[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Interprocess Communication Considerations Considerations for READUPDATEX Only Errors for READUPDATEX Only Related Programming Manuals Summary The READUPDATE[X] procedures read data from a disk or process file in anticipation of a subsequent write to the file.
READUPDATE[X] Procedures Guardian Procedure Calls (R) Syntax for C Programmers #include _cc_status READUPDATE ( short filenum ,short _near *buffer ,short read-count ,[ short _near *count-read ] ,[ __int32_t tag ] ); #include _cc_status READUPDATEX ( short filenum ,char *buffer ,short read-count ,[ short *count-read ] ,[ __int32_t tag ] ); • • CEXTDECS (via the included file TNSINTH) defines 32-bit values as the typedef __int32_t which for TNS and TNS/R co
READUPDATE[X] Procedures Guardian Procedure Calls (R) input read-count INT:value (Use with READUPDATE and READUPDATEX) is the number of bytes to be read. {0:4096} {0:57344} for disk files (see “Disk File Considerations”) for $RECEIVE output count-read INT:ref:1 (Use with READUPDATE) INT .EXT:ref:1 (Use with READUPDATEX) is for wait I/O only. count-read returns a count of the number of bytes returned from the file into buffer.
Guardian Procedure Calls (R) • READUPDATE[X] Procedures Random processing and positioning A call to READUPDATE[X] returns the record from the current position in the file. Because READUPDATE[X] is designed for random processing, it cannot be used for successive positioning through a subset of records as the READ[X] procedure does. Rather, READUPDATE[X] reads a record after a call to POSITION or KEYPOSITION, possibly in anticipation of a subsequent update through a call to the WRITEUPDATE[X] procedure.
Guardian Procedure Calls (R) • READUPDATE[X] Procedures Value of the current key and current-key specifier For key-sequenced, relative, and entry-sequenced files, random processing implies that a designated record must exist. Therefore, positioning for READUPDATE[X] is always to the record described by the exact value of the current key and current-key specifier. If such a record does not exist, the call to READUPDATE[X] is rejected with a file-system error 11 (“record does not exist”).
Guardian Procedure Calls (R) • • READUPDATE[X] Procedures pointer action for unstructured files is unaffected.
Guardian Procedure Calls (R) READUPDATE[X] Procedures Considerations for READUPDATEX Only • • • • • • • • • • The buffer and count transferred may 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. Flat segments allocated by a process are always accessible to the process.
Guardian Procedure Calls (R) READUPDATE[X] Procedures Related Programming Manuals For programming information about the READUPDATE file-system procedure, refer to the Guardian Programmer’s Guide and the Enscribe Programmer’s Guide.
Guardian Procedure Calls (R) READUPDATELOCK[X] Procedures READUPDATELOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Considerations for READUPDATELOCKX Only Errors for READUPDATELOCKX Only OSS Considerations Example Related Programming Manuals Summary The READUPDATELOCK[X] procedures are used for random processing of records in a disk file.
READUPDATELOCK[X] Procedures Guardian Procedure Calls (R) Syntax for C Programmers #include _cc_status READUPDATELOCK ( short filenum ,short _near *buffer ,short read-count ,[ short _near *count-read ] ,[ __int32_t tag ] ); #include _cc_status READUPDATELOCKX ( short filenum ,char *buffer ,short read-count ,[ short *count-read ] ,[ __int32_t tag ] ); • • CEXTDECS (via the included file TNSINTH) defines 32-bit values as the typedef __int32_t which
READUPDATELOCK[X] Procedures Guardian Procedure Calls (R) input read-count INT:value (Use with READUPDATELOCK and READUPDATELOCKX) is the number of bytes to be read {0:4096}. output count-read INT:ref:1 (Use with READUPDATELOCK) INT .EXT:ref:1 (Use with READUPDATELOCKX) is for wait I/O only. count-read returns a count of the number of bytes returned from the file into buffer. input tag INT(32):value (Use with READUPDATELOCK and READUPDATELOCKX) is for nowait I/O only.
Guardian Procedure Calls (R) READUPDATELOCK[X] Procedures READUPDATELOCKX is used, the user must call the AWAITIOX procedure to complete the I/O. If READUPDATELOCK is used, the user may use either AWAITIO or AWAITIOX to complete the I/O. • • If READUPDATELOCK[X] is performed on nondisk files, an error is returned. Random processing For key-sequenced, relative, and entry-sequenced files, random processing implies that a designated record must exist.
Guardian Procedure Calls (R) • • READUPDATELOCK[X] Procedures A file opened by FILE_OPEN_ uses direct I/O transfers by default; you can use SETMODE 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.
Guardian Procedure Calls (R) RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ Procedure ) 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.
RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ Guardian Procedure Calls (R) Syntax for TAL Programmers CALL RECEIVEINFO ( [ ,[ ,[ ,[ ,[ ,[ process-id ] message-tag ] sync-id ] filenum ] read-count ] iotype ] ); ! ! ! ! ! ! o o o o o o Parameters output process-id INT:ref:4 returns the 4-word process ID of the process that sent the last message read through the $RECEIVE file.
Guardian Procedure Calls (R) RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ currently queued. To associate a reply with a given request, message-tag is passed in a parameter to the REPLY procedure. The returned value of messagetag is an integer between zero and receive depth -1, inclusive, that is not currently used as a message tag. When a reply is made, its associated message tag value is made available for use as a message tag for a subsequent request message.
Guardian Procedure Calls (R) RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ Considerations • Process ID and RECEIVEINFO The 4-word process ID returned by RECEIVEINFO following receipt of a process open, close, CONTROL, SETMODE, SETPARAM, RESETSYNC, or CONTROLBUF system message, or a data message, identifies the process associated with the operation.
Guardian Procedure Calls (R) • RECEIVEINFO Procedure (Superseded by FILE_GETRECEIVEINFO_ Duplicate requests The sync-id parameter allows the server process (that is, the process reading $RECEIVE) to detect duplicate requests from requester processes. Such duplicate requests are caused by a backup requester process reexecuting the latest request of a failed primary requester process. Note.
Guardian Procedure Calls (R) REFPARAM_BOUNDSCHECK_ Procedure REFPARAM_BOUNDSCHECK_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Summary Note. This procedure is declared only in the EXTDECS0 file. The REFPARAM_BOUNDSCHECK_ procedure checks the validity of parameter addresses passed to the procedure that calls it. Bounds checking performed by the system is enough for most applications.
Guardian Procedure Calls (R) REFPARAM_BOUNDSCHECK_ Procedure 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_ ( start-address ,area-length ,framestart ,flags ); ! ! ! ! i i i i Parameters returned value error INT returns one of the following values: 0 No error.
Guardian Procedure Calls (R) REFPARAM_BOUNDSCHECK_ Procedure start-address input STRING .EXT:ref:* identifies the start of the data area to be bounds checked. When REFPARAM_BOUNDSCHECK_ is called from a native process, startaddress cannot be a relative segment 1 or 2 address. Neither can it be an absolute address unless flags.<14> is set to allow this. When REFPARAM_BOUNDSCHECK_ is called from a TNS process, startaddress can be an absolute address that points to the TNS stack.
Guardian Procedure Calls (R) REFPARAM_BOUNDSCHECK_ Procedure input flags INT:value specifies options. The bits indicate the following: <0:13> must be zero. <14> = 0 specifies that absolute addressing is not allowed for native processes. = 1 allows absolute addressing even if REFPARAM_BOUNDSCHECK_ is called from a native process. No checking is performed and REFPARAM_BOUNDSCHECK_ returns without error. <15> = 0 checks the area for read/write access. = 1 checks the area for read-only access.
Guardian Procedure Calls (R) REFPARAM_BOUNDSCHECK_ Procedure allocates more space for the segment. If no space is available, REFPARAM_BOUNDSCHECK_ returns error 3. • To exclude address references from the stack area used by the calling procedure, use DEFINES with the framestart parameter as follows: 1. Invoke the _FRAME_EDGE_DEF DEFINE among the declarations in the procedure. 2. Pass the names of the first and last parameters of the procedure to the _FRAME_EDGE_DEF DEFINE.
Guardian Procedure Calls (R) REFRESH Procedure (Superseded by DISK_REFRESH_ Procedure ) REFRESH Procedure (Superseded by DISK_REFRESH_ 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. On G-series RVUs, the function provided by both the REFRESH and DISK_REFRESH_ procedures is no longer needed.
REFRESH Procedure (Superseded by DISK_REFRESH_ Procedure ) Guardian Procedure Calls (R) Syntax for TAL Programmers error := REFRESH ( [volname] ); ! i Parameters returned value error INT returns a file-system error number indicating the outcome of the call. (Refer to the Guardian Procedure Errors and Messages Manual for a list of all file-system errors.) input volname INT:ref:12 specifies a volume whose associated FCBs should be written to disk.
REMOTEPROCESSORSTATUS Procedure Guardian Procedure Calls (R) REMOTEPROCESSORSTATUS Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary The REMOTEPROCESSORSTATUS procedure supplies the status of processor modules in a particular system in a network.
REMOTEPROCESSORSTATUS Procedure Guardian Procedure Calls (R) input sysnum INT:value is the number of a particular system in a network whose processor modules’ status is returned. 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.
REMOTETOSVERSION Procedure Guardian Procedure Calls (R) REMOTETOSVERSION Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Related Programming Manual Summary The REMOTETOSVERSION procedure identifies which version of the operating system is running on a remote system.
Guardian Procedure Calls (R) REMOTETOSVERSION Procedure input sysid INT:value is the system number that identifies the system for which the operating system version is returned. If sysid is omitted, it defaults to the local system. Example REMOTE^VERSION := REMOTETOSVERSION ( SYSTEM^NUM ); For example, if the operating-system version is D10, the returned value contains “N” in bits <0:7> and binary 10 in bits <8:15>.
Guardian Procedure Calls (R) RENAME Procedure (Superseded by FILE_RENAME_ Procedure ) 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.
RENAME Procedure (Superseded by FILE_RENAME_ Procedure ) Guardian Procedure Calls (R) input new-name INT:ref:12 is an array containing the internal-format file name to be assigned to the disk file, as follows: $volname (blank-fill) [0:3] or \sysnum volname (blank-fill) [4:7] subvolname (blank-fill) [8:11] file-id (blank-fill) Condition Code Settings < (CCL) indicates that an error occurred (call FILEINFO or FILE_GETINFO_). = (CCE) indicates that the rename operation is successful.
Guardian Procedure Calls (R) RENAME Procedure (Superseded by FILE_RENAME_ Procedure ) If the primary-key file is renamed, it is linked with the alternate-key file. If you rename the alternate-key file and then try to access the primary-key file, filesystem error 4 occurs, because the primary-key file is still linked with the old name for the alternate-key file. You can use the FUP ALTER command to correct this problem.
REPLY[X] Procedures Guardian Procedure Calls (R) REPLY[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Considerations for REPLYX Only Errors for REPLYX Only Example Related Programming Manual Summary The REPLY[X] procedures are used to send a reply message to a message received earlier in a corresponding call to READUPDATE[X] on the $RECEIVE file.
REPLY[X] Procedures Guardian Procedure Calls (R) Syntax for TAL Programmers CALL REPLY[X] ( [ ,[ ,[ ,[ ,[ buffer ] write-count ] count-written ] message-tag ] error-return ] ); ! ! ! ! ! i i o i i Parameters input buffer INT:ref:* (Use with REPLY) STRING .EXT:ref:* (Use with REPLYX) is an array containing the reply message. input write-count INT:value (Use with REPLY and REPLYX) is the number of bytes to be written ({0:57344}). If omitted, no data is transferred.
REPLY[X] Procedures Guardian Procedure Calls (R) input error-return INT:value (Use with REPLY and REPLYX) is an error indication that is returned, when the originator’s I/O operation completes, to the originator associated with this reply. This indication appears to the originator as a normal file-system error return. The originator’s condition code is set according to the relative value of error-return.
Guardian Procedure Calls (R) • REPLY[X] Procedures Using the message-tag If more than one message is queued by the application process (that is, receivedepth > 1), a message tag associated with each incoming message must be obtained in a call to the FILE_GETRECEIVEINFO_ (or LASTRECEIVE or RECEIVEINFO) procedure immediately following each call to READUPDATE[X].
Guardian Procedure Calls (R) REPLY[X] Procedures Related Programming Manual For programming information about the REPLY[X] file-system procedure, refer to the Guardian Programmer’s Guide.
REPOSITION Procedure (Superseded by FILE_RESTOREPOSITION_ Guardian Procedure Calls (R) 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).
Guardian Procedure Calls (R) REPOSITION Procedure (Superseded by FILE_RESTOREPOSITION_ positioning-block input INT:ref:* indicates a saved position to be repositioned to. This should not be altered by the user. Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that REPOSITION is successful. > (CCG) indicates that the file is not a disk file. Considerations • The REPOSITION procedure cannot be used with format 2 files.
RESETSYNC Procedure Guardian Procedure Calls (R) RESETSYNC Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (R) RESETSYNC Procedure Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that RESETSYNC is successful. > (CCG) indicates that the file is not a disk file. 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.
Guardian Procedure Calls (R) RESIZEPOOL Procedure (Superseded by POOL_* Procedures) RESIZEPOOL Procedure (Superseded by POOL_* Procedures) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development. *POOL procedures are replaced by POOL_* procedures. There is no one-for-one replacement.
Guardian Procedure Calls (R) RESIZEPOOL Procedure (Superseded by POOL_* Procedures) 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. 59 The pool is invalid and cannot be resized. input, output pool-head INT .EXT:ref:19 is a 19-word pool header previously initialized through a call to the DEFINEPOOL procedure. RESIZEPOOL updates this header to reflect the new pool size.
Guardian Procedure Calls (R) RESIZESEGMENT Procedure RESIZESEGMENT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Considerations for Privileged Callers Example Related Programming Manual Summary RESIZESEGMENT alters the size of an existing extended data segment (for example, a segment created by SEGMENT_ALLOCATE_ ).
Guardian Procedure Calls (R) RESIZESEGMENT Procedure 12 Indicates one of the following conditions. • • • • Because the extended data segment is a shared segment, the segment cannot be reduced (see “Considerations”). Because an I/O to the segment is in progress, the segment cannot be reduced. The segment is being resized. There is a lockmemory request on the segment. 21 An invalid new-segment-size was specified (see new-segment-size, below).
Guardian Procedure Calls (R) RESIZESEGMENT Procedure Considerations • The following extended data segment types cannot be resized (an attempt to do so results in an error 2): • • An extended data segment allocated in the I/O space (IOS) (a segment with a segment ID greater than or equal to 3072). A read-only extended data segment (created by calling SEGMENT_ALLOCATE_ with a segment-type parameter of %060000 or by calling ALLOCATESEGMENT with a pin-and-flags parameter of %060000).
RESIZESEGMENT Procedure Guardian Procedure Calls (R) • A call to RESIZESEGMENT causes disk extents to be allocated or deallocated (for file-backed segments), or page reservations to be increased or decreased (for KMSF-backed segments) in the following ways: Type of segment At segment allocate At memory access At segment resize File-backed nonextensible segment File extents are completely allocated. Number of allocated extents does not change. Growing: additional extents are allocated.
Guardian Procedure Calls (R) RESIZESEGMENT Procedure Considerations for Privileged Callers • • Following a call to RESIZESEGMENT, any underlying absolute segments allocated to the specified extended data segment might change if the resize causes the segment to be extended. Privileged users must not use absolute addresses to reference locations in any extended data segment that could be resized.
14 Guardian Procedure Calls (S) This section contains detailed reference information for all user-accessible Guardian procedure calls beginning with the letter S. Table 14-1 lists all the procedures in this section. Table 14-1.
Guardian Procedure Calls (S) Table 14-1.
SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure) Guardian Procedure Calls (S) 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.
Guardian Procedure Calls (S) SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure) Parameters input filenum INT:value is a number of an open file, identifying the file whose positioning block is to be obtained. positioning-block output INT:ref:* returns the positioning information for the file’s current position. The buffer must be large enough to hold the entire block of information. The following shows how to calculate the required buffer size in words.
Guardian Procedure Calls (S) SAVEPOSITION Procedure (Superseded by FILE_SAVEPOSITION_ Procedure) Considerations • • • For relative and entry-sequence files that have no alternate keys. SAVEPOSITION requires a 7-word positioning-block if read-reverse is the current reading mode (see the KEYPOSITION[X] procedures). The SAVEPOSITION procedure cannot be used with format 2 files. If an attempt is made to use the SAVEPOSITION procedure with format 2 files, error 581 is returned.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure SEGMENT_ALLOCATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Examples Related Programming Manual Summary The SEGMENT_ALLOCATE_ procedure allocates an extended data segment for use by the calling process. This procedure can create read/write segments, read-only segments, and extensible segments.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure #include short SEGMENT_ALLOCATE_ ( short segment-id /* i 1 */ ,[ __int32_t segment-size ] /* i 2 */ ,[ char *filename ] /* i:i 3 */ ,[ short length ] /* i:i 3 */ ,[ short *error-detail ] /* o 4 */ ,[ short pin ] /* i 5 */ ,[ short segment-type ] /* i 6 */ ,[ __int32_t *base-address ]] /* i,o 7 */ ,[ __int32_t max-size ] /* i 8 */ ,[ short alloc-options ]););/*i 9*/ • The parameter length specifies the length in bytes
Guardian Procedure Calls (S) 9 10 11 12 SEGMENT_ALLOCATE_ Procedure pin does not exist. pin does not have the segment allocated. Caller is trying to share segment with self. Indicates one of three conditions: (1) The requested segment is a shared selectable segment, but the allocated segment is a flat segment. (2) The requested segment is a shared flat segment, but the allocated segment is a selectable segment. (3) The segment is being resized.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure attempt to allocate an 1120 MB segment in a native program results in an error 15. ° • The 32-megabyte region boundary does not apply in the G05.00 and later G-series RVUs. For a selectable segment, the value must be in the range 1 byte through 127.5 megabytes (133,693,440 bytes). The system might round the size up to the next segment-size increment, where the increment is both processor-dependent and subject to change.
Guardian Procedure Calls (S) • • SEGMENT_ALLOCATE_ Procedure If the swap file has not been opened in this processor by a previous call to SEGMENT_ALLOCATE_, the size of the segment will be set to segment-size, if supplied. If segment-size was not supplied, the size defaults to the size of the existing swap file.
Guardian Procedure Calls (S) • SEGMENT_ALLOCATE_ Procedure Existing permanent swap file If supplied and if length is not 0, specifies the name of a swap file to be associated with the segment. If used, the value of filename must be exactly length bytes long. If the file name is partially qualified (for example, without the volume name), it is resolved using the contents of the =_DEFAULTS DEFINE. All data in the file is used as initial data for the segment.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure if present and not equal to -1, requests allocation of a segment that is shared by the PIN method. pin specifies 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.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure 1 Allocate an extensible segment; sharing by the PIN method can be specified. 2 Allocate a segment with sharing by the file name method. 3 Allocate an extensible segment with sharing by the file name method. 4, 6Allocate a read-only segment; sharing by either the PIN method or the file name method can be specified. base-address input,output EXTADDR .EXT:ref:1 if used as an output parameter, returns the base address of the segment being allocated.
SEGMENT_ALLOCATE_ Procedure Guardian Procedure Calls (S) processes that still shares the segment. The SEGMENT_ALLOCATE_ call in the sharer will fail with error 15 in the following cases: 1. Another segment in the sharer is already mapped at this base-address, OR 2. The address range of the segment to be shared overlaps with that of another segment in the sharer.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure The default value of alloc-options is all bits equal to 0, which means that a selectable segment is allocated and the base address is returned in the baseaddress parameter. Considerations Note. There are additional considerations for privileged callers. • Preventing automatic temporary file purge SEGMENT_ALLOCATE_ opens the swap file for read/write/protected access.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_ Procedure process cannot share a selectable segment with a process that allocated a flat segment.) • Flat segments and increased performance Although the SEGMENT_USE_ and MOVEX procedures can be used with flat segments, you can improve performance by eliminating SEGMENT_USE_ calls and replacing MOVEX calls with direct assignment statements.
SEGMENT_ALLOCATE_ Procedure Guardian Procedure Calls (S) To satisfy various hardware and software constraints and requirements for finding addresses within the virtual memory space, the space is divided into regions, segments, and pages.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_CHKPT_ Procedure SEGMENT_ALLOCATE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_CHKPT_ Procedure filename:length input:input STRING .EXT:ref:*, INT:value indicates several types of swap files: temporary swap space using KMSF, temporary swap file, existing permanent swap file, new permanent swap file, and segment sharing by the file-name method If filename is specified, pin must be omitted.
SEGMENT_ALLOCATE_CHKPT_ Procedure Guardian Procedure Calls (S) If the process terminates without deallocating the segment, any data still in memory is written back out to the file. Unless the segment is extensible, SEGMENT_ALLOCATE_CHKPT_ must be able to allocate a sufficient number of file extents to contain all memory in the segment. • New permanent swap file If supplied, if length is not 0, and if filename does not exist, specifies the name of a swap file to be created.
Guardian Procedure Calls (S) SEGMENT_ALLOCATE_CHKPT_ Procedure input pin INT:value if present and not -1, requests allocation of a segment that is shared by the PIN method. pin specifies the process identification number of the process that has previously allocated the segment and with which the caller wishes 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.
Guardian Procedure Calls (S) • • • SEGMENT_ALLOCATE_CHKPT_ Procedure Any process that has the same process access ID (PAID) Any process that has the same group ID, if $X is the group manager (that is, if $X has a PAID of group,255) Any process, if $X has a PAID of the super ID (255,255) 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.
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_ Procedure SEGMENT_DEALLOCATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The SEGMENT_DEALLOCATE_ procedure deallocates an extended data segment.
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_ Procedure input segment-id INT:value specifies the segment ID of the segment to be deallocated. The segment ID was assigned by the program in the call to SEGMENT_ALLOCATE_ that allocated the segment. input flags INT:value specifies whether dirty pages must be written to the swap file. A dirty page is a page in memory that has been updated but not written to the swap file.
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_ Procedure modified (“dirty”) pages, it might take a long time to deallocate the segment. If flags.<15> is set to 1, the modified pages are not written to the swap file, even if it is a permanent file. This option is recommended when the swap file has been made permanent to reserve the swap file space, or when the file contents are unimportant for any reason.
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_CHKPT_ Procedure SEGMENT_DEALLOCATE_CHKPT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_CHKPT_ Procedure input flags INT:value specifies whether dirty pages must be written to the swap file. A dirty page is a page in memory that has been updated but not written to the swap file. Valid values are: <0:14> Reserved (specify 0) <15> 1 Indicates that dirty pages in memory are not to be written to the swap file. 0 Indicates that dirty pages in memory are to be written to the swap file. The default is 0. error-detail output INT .
Guardian Procedure Calls (S) SEGMENT_DEALLOCATE_CHKPT_ Procedure been made permanent to reserve the swap file space, or when the file contents are unimportant for any reason. • Breakpoints Before deallocating a segment, SEGMENT_DEALLOCATE_CHKPT_ removes all memory access breakpoints set in that segment.
Guardian Procedure Calls (S) SEGMENT_GETBACKUPINFO_ Procedure SEGMENT_GETBACKUPINFO_ Procedure Summary Syntax for TAL Programmers Parameters Summary The SEGMENT_GETBACKUPINFO_ procedure retrieves information about an extended segment that is allocated by the backup process in a named process pair.
Guardian Procedure Calls (S) SEGMENT_GETBACKUPINFO_ Procedure output segment-size INT(32) .EXT:ref:1 returns the current size in bytes of the specified segment. The size might be rounded up from what was specified when the segment was allocated. See the description of segment-size under SEGMENT_ALLOCATE_ for details. filename:maxlen output:input STRING .EXT:ref:*, INT:value if present and maxlen is not 0, returns the fully qualified name of the segment’s swap file.
Guardian Procedure Calls (S) • SEGMENT_GETBACKUPINFO_ Procedure For a selectable segment, base-address is always %2000000D (%H00080000).
Guardian Procedure Calls (S) SEGMENT_GETINFO_ Procedure SEGMENT_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The SEGMENT_GETINFO_ procedure retrieves information about a currently allocated extended data segment. Syntax for C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (S) SEGMENT_GETINFO_ Procedure Parameters returned value error INT Indicates the outcome of the operation. Returns one of the following values: 0 No error 1 Error occurred when attempting to obtain filename; 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.
Guardian Procedure Calls (S) SEGMENT_GETINFO_ Procedure filename-len output INT .EXT:ref:1 returns the length in bytes of the swap-file name being returned. If the segment is managed by the Kernel-Managed Swap Facility (KMSF), filename-len is set to 0. For more information on KMSF see the KernelManaged Swap Facility (KMSF) Manual. error-detail output INT .EXT:ref:1 returns additional information associated with some errors. See error for details. base-address output EXTADDR .
Guardian Procedure Calls (S) SEGMENT_GETINFO_ Procedure Considerations See Considerations on page 14-15 for the SEGMENT_ALLOCATE_ procedure. Example error := SEGMENT_GETINFO_ ( segment^id, seg^size, swap^file:length ); Related Programming Manual For programming information about the SEGMENT_GETINFO_ procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (S) SEGMENT_USE_ Procedure SEGMENT_USE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) SEGMENT_USE_ Procedure #include short SEGMENT_USE_ ( short new-segment-id ,[ short *old-segment-id ] ,[ __int32_t *base-address ] ,[ short *error-detail ] ); Syntax for TAL Programmers error := SEGMENT_USE_ ( new-segment-id ,[ old-segment-id ] ,[ base-address ] ,[ error-detail ] ); ! ! ! ! i o o o Parameters returned value error INT indicates the outcome of the operation.
Guardian Procedure Calls (S) SEGMENT_USE_ Procedure 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 .
Guardian Procedure Calls (S) SEGMENTSIZE Procedure (Superseded by SEGMENT_GETBACKUPINFO_ Procedure ) SEGMENTSIZE Procedure (Superseded by SEGMENT_GETBACKUPINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) SEGMENTSIZE Procedure (Superseded by SEGMENT_GETBACKUPINFO_ Procedure ) Example INT(32) seglen := 0D; INT segid := 2; ! pass to SEGMENTSIZE later . . seglen := SEGMENTSIZE ( segid ); IF seglen = -1D THEN ...
SENDBREAKMESSAGE Procedure (Superseded by BREAKMESSAGE_SEND_ Guardian Procedure Calls (S) SENDBREAKMESSAGE Procedure (Superseded by BREAKMESSAGE_SEND_ 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. SENDBREAKMESSAGE allows user processes to send break-on-device messages to other processes.
Guardian Procedure Calls (S) SENDBREAKMESSAGE Procedure (Superseded by BREAKMESSAGE_SEND_ input process-id INT .EXT:ref:4 identifies the process to which the break-on-device message is to be sent. The format of the 4-word process ID is: [0:2] [3].<0:3> .<4:7> .<8:15> Process name or creation timestamp Reserved Processor number where the process is executing PIN assigned by the operating system to identify the process in the processor input breaktag INT .
Guardian Procedure Calls (S) SET^FILE Procedure SET^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example 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.
SET^FILE Procedure Guardian Procedure Calls (S) Syntax for TAL Programmers For pTAL callers, the procedure definition is: error := SET^FILE ( { common-fcb } { file-fcb } ,operation ,[ new-value ] ,[ old-value ] ,[ setaddr-value ]); ! ! ! ! ! ! i i i i o i ! ! ! ! ! i i i i o For other callers, the procedure definition is: error := SET^FILE ( { common-fcb } { file-fcb } ,operation ,[ new-value ] ,[ old-value ] ); Parameters returned value error INT returns a file-system or sequential I/O (SIO) proc
Guardian Procedure Calls (S) SET^FILE Procedure When using INIT^FILEFCB, INIT^FILEFCB^D00, FILE^FWDLINKFCB, FILE^BWDLINKFCB, and SET^TRACEBACK, the FCB can be specified as the common-fcb or the file-fcb. If an improper FCB is specified or the FCB is not initialized, an error is indicated. input operation INT:value specifies the file characteristic to be altered. (See Table 14-2 on page 14-46 and Table 14-3 on page 14-56.) input new-value INT:value specifies a new value for the specified operation.
SET^FILE Procedure Guardian Procedure Calls (S) • The ASSIGN^SECEXT operation comes into effect only when an ASSIGN^PRIEXT (or ASSIGN^PRIMARYEXTENTSIZE) operation is specified. If the primary extent (ASSIGN^PRIEXT) has not been set explicitly, any command to set the secondary extent (ASSIGN^SECEXT) will be ignored, and the secondary extent will have the default value. The following table describes operations that set values in the new-value parameter. . Table 14-2.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 2 of 10) ASSIGN^ OPENEXCLUSION Specifies the open exclusion for the file.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 3 of 10) Specifies that the file FCB be initialized. This operation is not used when the INITIALIZER procedure is called to initialize the FCBs. It is valid only for C-series format FCBs.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 4 of 10) operation Description of Operation Requested new-value old-value State of File SET^ABORT^ XFERERR Sets or clears abort-ontransfer error for the file. If on, and a fatal error occurs during a datatransfer operation (such as a call to any SIO procedure except OPEN^FILE), all files are closed and the process abnormally ends.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 5 of 10) Description of Operation Requested operation new-value old-value State of File SET^COUNTXFERRED Sets the physical I/O count, in bytes, transferred for the file. This is used only if nowait I/O is in effect and the user is making the call to AWAITIO for the file. This is the parameter value returned from AWAITIO.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 6 of 10) SET^EDITREAD^ REPOSITION Specifies that the following READ^FILE is to begin at the position set in the sequential block buffer (second through fourth words).
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 7 of 10) Description of Operation Requested new-value old-value SET^PROMPT Sets interactive prompt for the file. See the OPEN^FILE procedure. Open SET^RCVEOF Sets return end of file (EOF) on process close for $RECEIVE file. This causes an EOF indication to be returned from READ^FILE when the receive open count goes from 1 to 0.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 8 of 10) If is 0, a return from READ^FILE is made only when data is received. old-value Open SET^ RCVUSEROPENREPLY ( continued ) new-value Open Description of Operation Requested operation State of File Note: If open message = 1 is specified to SET^SYSTEMMESSAG ES or SET^SYSTEMMESSAG ESMANY, the setting of SET^ RCVUSEROPENREPLY has no meaning.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 9 of 10) Description of Operation Requested operation .<15> = unused SET^TRACEBACK Sets or clears the traceback feature. When traceback is active, the SIO facility appends the caller's Prelative address to all error messages. SET^USERFLAG Sets user flag for the file.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-2. SET^FILE Operations That Set Values (page 10 of 10) operation Description of Operation Requested new-value old-value State of File SET^WRITE^FOLD Sets or clears write-fold for the file. If on, write^file operations exceeding the record length cause multiple logical records to be written. If off, write^file operations exceeding the record length are truncated to recordlength bytes; no error message or warning is given.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-3. SET^FILE Operations That Set Addresses (page 1 of 5) Description of Operation Requested operation Sets system message reception for the $RECEIVE file. is a fourword mask. Setting a bit in indicates that the corresponding message is to pass back to the user. Default action is for the SIO procedures to handle all system messages.
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-3. SET^FILE Operations That Set Addresses (page 2 of 5) Description of Operation Requested operation SET^ SYSTEMMESSAGES MANY (word 0 ) setaddrvalue or new-value [0] .<0:1>= unused .<2> = processor down message .<3> = processor up message .<4> = unused .<5> = process deletion message if D-series format; STOP message if C-series format .<6> = unused if Dseries format; ABEND message if Cseries format .<7> = unused .
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-3. SET^FILE Operations That Set Addresses (page 3 of 5) Description of Operation Requested operation SET^ SYSTEMMESSAGES MANY (continued: word 1 ) [1] .<0:3>= unused .<4> = BREAK message setaddrvalue or new-value old-value @ .<5> = unused .<6> = time signal message (NonStop II systems only) .<7> = memory lock completion message (NonStop II systems only) .
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-3. SET^FILE Operations That Set Addresses (page 4 of 5) Description of Operation Requested operation SET^ SYSTEMMESSAGES MANY (continued: word 2 ) setaddrvalue or new-value [2] .<0> = CONTROL message .<1> = SETMODE message .<2> = RESETSYNC message .<3> = CONTROLBUF message .<4:7>= unused .<8> = device-type inquiry if D-series format; unused if Cseries format .
SET^FILE Procedure Guardian Procedure Calls (S) Table 14-3. SET^FILE Operations That Set Addresses (page 5 of 5) Description of Operation Requested operation SET^ SYSTEMMESSAGES MANY (continued: word 3 ) setaddrvalue or new-value old-value State of File [3] .<0> = nowait PROCESS_CRE ATE_ completion .<1> = subordinate name inquiry .<2> = nowait get info by name completion .<3> = nowait FILENAME_FIN DNEXT_ completion .<4> = loss of communication with node .
SETJMP_ Procedure Guardian Procedure Calls (S) SETJMP_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.SYSTEM.
Guardian Procedure Calls (S) SETJMP_ Procedure output env INT .EXT:ref:(JMP_BUF_TEMPLATE) specifies the address of a previously allocated jump buffer in which the process context of the caller is returned. The jump buffer is allocated using the JMP_BUF_DEF DEFINE. Considerations • • • SETJMP_ is the TAL or pTAL procedure name for the C setjmp() function. The C setjmp() function complies with the POSIX.1 standard.
SETLOOPTIMER Procedure Guardian Procedure Calls (S) SETLOOPTIMER Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations OSS Considerations Example Summary A call to 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.
Guardian Procedure Calls (S) SETLOOPTIMER Procedure If the value of new-time-limit is 0, process loop timing is disabled. old-time-limit output INT:ref:1 returns the current setting of the process’s loop timer (in 0.01-second units). 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’s loop timer are unchanged.
Guardian Procedure Calls (S) SETLOOPTIMER Procedure For example, a process’s main execution loop can be written as follows: --> | | | start: | CALL SETLOOPTIMER ( 1000 ); | IF < THEN ... ; | | . | | . ! enable loop timing. | | . ! Time-limit value is 10 seconds. | | . | CALL WRITEREAD ( termfnum ,... ); | | . | | . ! process executes when terminal input is made. | | . ! Loop-timer value is not decremented while | | . ! process is suspended waiting for I/O. | | | terminal input is processed.
SETMODE Procedure Guardian Procedure Calls (S) SETMODE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings SETMODE Functions Considerations Disk File Consideration Interprocess Communication Considerations Messages Examples Related Programming Manuals Summary The SETMODE procedure is used to set device-dependent functions.
SETMODE Procedure Guardian Procedure Calls (S) Syntax for TAL Programmers CALL SETMODE ( filenum ,function ,[ param1 ] ,[ param2 ] ,[ last-params ] ); ! ! ! ! ! i i i i o Parameters input filenum INT:value is a number of an open file that identifies the file to receive the SETMODE function. input function INT:value is one of the device-dependent functions listed in Table 14-4 on page 14-68. input param1 INT:value is one of the parameters listed in Table 14-4 on page 14-68.
Guardian Procedure Calls (S) SETMODE Procedure = (CCE) indicates that the SETMODE is successful. > (CCG) indicates that the SETMODE function is not allowed for this device type. SETMODE Functions Table 14-4 on page 14-68 lists the SETMODE functions that can be used with the I/O devices discussed in this manual for NonStop servers. Table 14-4.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 2 of 34) function Parameters and Effect This function operates only on Guardian objects. If an OSS file is specified, file-system error 2 occurs. 2 Disk: Set file owner param1.<0:7> = .<8:15> = group ID member ID param2 is not used with function 2.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 3 of 34) function Parameters and Effect 4 Disk: Set lock mode. Note that this operation is not supported for queue files. param1 = 0 normal mode (default): request is suspended when a read or lock is attempted and an established record lock or file lock is encountered.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 4 of 34) function Parameters and Effect 5 Line printer: Set system automatic perforation skip mode (assumes standard VFU function in channel 2) param1.<15> = 0 off, 66 lines per page = 1 on, 60 lines per page (default) For the 5530 line printer: param1 = 0 disable automatic perforation skip. = 1 enable automatic perforation skip (default). param2 is not used with function 5.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 5 of 34) function Parameters and Effect 9 Terminal: Set interrupt characters param1.<0:7> = character 1 .<8:15> = character 2 param2.<0:7> = character 3 .<8:15> = character 4 (Default for conversational mode is backspace, line cancel, end of file, and line termination. Default for page mode is page termination.) See discussion of “interrupt characters” in the Guardian Programmer’s Guide.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 6 of 34) function Parameters and Effect 13 Terminal: Set system read termination on ETX character (default is configured) param1 = 0 no termination on ETX = 1 termination on first character after ETX = 3 termination on second character after ETX param2 is used, with ATP6100 only, to specify the value of the ETX character.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 7 of 34) function Parameters and Effect 22 Line printer (subtype 3, 4, 6, and 32) or terminal: Set baud rate param1 = 0 baud rate = 50 1 baud rate = 75 2 baud rate = 110 3 baud rate = 134.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 8 of 34) function Parameters and Effect 22, continued You can specify split baud rates with the LIU-4 controller as follows. Note that the values for param1 all have bit 0 set to 1: param1 = 128 TX baud rate = 50 129 TX baud rate = 75 130 TX baud rate = 110 131 TX baud rate = 134.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 9 of 34) function Parameters and Effect 22, continued If you specify split baud rates with the LIU-4 controller, the last-params parameter returns the following values: last-params[0] .<0:7>param1 value (TX) .
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 10 of 34) function Parameters and Effect 28 Line printer or terminal: Reset to configured values param1 = 0 (default) resets printer to its configured values = 1 resets only soft parameters = 2 resets only hard parameters param2 is not used with function 28. For the 5530 line printer, SETMODE 28 resets all the SETMODE parameters back to their configuration values and also reinitializes the printer.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 11 of 34) function Parameters and Effect 31 Set packet mode param1.<0> param2 = 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. 32 Set X.25 call setup parameters param1.<0> = 0 do not accept charge. = 1 accept charge. .
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 12 of 34) function Parameters and Effect 37 Line printer (subtype 1, 4, 5, or 6): Get device status param1 is not used with function 37. param2 is not used with function 37. last-params = status of device. Status values are: last-params for printer (subtype 1 or 5) (only last-params[0] is used) .<5> = DOV, data overrun 0 = no overrun 1 = overrun occurred .
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 13 of 34) function Parameters and Effect 37, continued last-params for printer (subtype 4) last-params [0] = primary status returned from printer: .<9:11> = full status field 0 = partial status 1 = full status 2 = full status / VFU fault 3 = reserved for future use 4 = full status / data parity error 5 = full status / buffer overflow 6 = full status / bail open 7 = full status / auxiliary status available .
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 14 of 34) function Parameters and Effect 37, continued Primary status bits are: [0].<0:8> = 0 undefined .<9> = 1 reserved .<10:12> = 0 no faults = 1 printer idle = 2 paper out = 3 end of ribbon = 4 data parity error = 5 buffer overflow = 6 cover open = 7 auxiliary status available .<13> = 0 buffer not full = 1 buffer full .<14> = 0 OK = 1 device power on error .
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 15 of 34) function Parameters and Effect 38 Terminal: Set special line-termination mode and character param1 38, continued param2 last-params = 0 sets special line-termination mode. param2 is the new line-termination character. The line-termination character is not counted in the length of a read. No system-supplied carriage return or line feed is issued at the end of a read (see note on cursor movement below).
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 16 of 34) function Parameters and Effect 52 Tape drive: Set short write mode param1 = 0 allow writes shorter than 24 bytes; a record shorter than 24 bytes is padded with zeros to a length of 24 bytes (default). = 1 disallow writes shorter than 24 bytes. = 2 allow writes shorter than 24 bytes; no padding is done on records shorter than 24 bytes. param2 is not used with function 52.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 17 of 34) function Parameters and Effect 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. param2 is not used with function 67.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 18 of 34) function Parameters and Effect 72 Force system buffering for nowait files = 1 force use of intermediate buffer in PFS for read operations. param1 (Nowait write operations always require the data to remain unchanged until completion of the information.) = 0 allow the system to make transfers directly from user buffers. The default value for files opened by FILE_OPEN_ is 0; for files opened by OPEN it is 1.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 19 of 34) function Parameters and Effect 91 Disk: Set cache and sequential option (function 91 is not applicable for alternate-key files). param1 = 0 system managed (default). DP2 will detect sequential access; when detected, it will set LRU access to sequential and perform key-sequenced sequential splits. = 1 direct I/O, bypass disk cache = 2 random access, LRU-chain buffer = 3 sequential access, reuse buffer.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 20 of 34) function Parameters and Effect 93 Disk: Set buffer length for an unstructured file new BUFFERSIZE value, must be valid DP2 block size. Valid DP2 block sizes are 512,1024, 2048, 4096 bytes (the default is 4096 bytes). param2 is not used with function 93. param1 = This function operates only on Guardian objects.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 21 of 34) 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.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 23 of 34) function Parameters and Effect 120 Return end-of-tape (EOT) message when writing labeled tapes param1 = 0 volume switching is transparent = 1 notify user of volume switch by sending error 150 (EOT). COBOL applications do not receive error 150 (EOT); the COBOL run-time library (RTL) handles this error transparently. param2 is not used with function 120.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 24 of 34) function Parameters and Effect 128 Queue files: Specifing timeout periods. param1 = param2 = the higher order word of the timeout value (in 0.01 second). the lower order word of the timeout value (in 0.01 second). The two words are combined to form a 32-bit integer for the timeout value.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 25 of 34) function Parameters and Effect 141 DP2 disk file: Enable/disable large transfers param1 = 1 enable large transfers = 0 disable large transfers (this is the default value when the file is opened.) param2 is not used with function 141. last-params[0] last-params[1] contains the previous setting of the large transfer mode flag.
Guardian Procedure Calls (S) SETMODE Procedure Table 14-4. SETMODE Functions (page 26 of 34) function Parameters and Effect 141, continued 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.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 27 of 34) function Parameters and Effect 141, continued f -1D positioning is used, the current EOF must be on a page boundary, otherwise the disk process returns an error. If -1D positioning is used or writes are done that change the EOF, some performance gains are lost. When the EOF is changed, DP2 must do extra checkpoints.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 28 of 34) function Parameters and Effect 144 Sets LU character set and double-byte character code param1 must be omitted for function 144. param2 must be omitted for function 144. last-params[0].<0> last-params[0].<1:7> = 0 no translation = 1 SNAX does EBCDIC/ASCII translation = IBM device type 1=IBM-3277 2=not 3277 or 3276 3=IBM-3276 last-params[0].<8:15> = last-params[1].
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 29 of 34) function Parameters and Effect 149 Disk: Alternate key insertion locking. Note that this operation is not supported for queue files. param1 = 0 no automatic locking (default): locking and unlocking during insertion is not automatically performed.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 30 of 34) function Parameters and Effect 153 Disk: Variable-length audit compression. (D10 and later RVUs. This function should be avoided if a fallback to a RVU earlier than D10 is possible.) Enable or disable variable-length audit compression for any structured Enscribe file. param1 = 1 enables variable-length audit compression. = 0 disables variable-length audit compression. param2 is not used with function 153.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 31 of 34) function Parameters and Effect 162 Override System Compression Default on 5190 Cartridge Tape param1 = 1 No data compression = 2 Data compression (IDRC) param2 is not used with function 162. Users of unlabeled tapes who do not want to use the default compression setting can use SETMODE 162 to override the default setting. BACKUP and FUP do not support this operation.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 32 of 34) function Parameters and Effect 165 SNAX:Exception response (ER) mode param1 = 0 disables ER mode. The LU sends outbound LU-LU FMD requests in definite response (DR) mode. This is the default value if SCF or SPI has not been used previously to configure ER mode; otherwise, the SCF or SPI configuration value is used. = 1 enables ER mode for applications existing prior to the introduction of ER mode.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 33 of 34) function Parameters and Effect 260 Printer: Enables PostScript printing for the FASTP print process and FASTPbased print processes. param1 = 2 The FASTP print process sends the PCL command to switch the printer to PostScript mode. At the end of each line, a system-generated carriage return is issued. At the end of the job and before the next job prints, the printer is returned to PCL mode.
SETMODE Procedure Guardian Procedure Calls (S) Table 14-4. SETMODE Functions (page 34 of 34) function Parameters and Effect 263 Telserv: Enables/Disables processing of CTRL-C (03 hex) as break character. param1 = 1 enables processing of CTRL-C (03 hex) as break character. Equivalent startup option is -BREAKDATA (default). = 0 disables processing of CTRL-C (03 hex) as break character. Equivalent startup option is -NOBREAKDATA. param2 is not used with function 263.
Guardian Procedure Calls (S) SETMODE Procedure 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 SETMODEs on Telserv are allowed before doing a CONTROL 11.
SETMODE Procedure Guardian Procedure Calls (S) Examples 1. LITERAL SECURITY = %0222; . . . CALL SETMODE ( FNUM , 1 , SECURITY ); The LITERAL above sets the file's security to: read write execute purge 2. = = = = any local user owner only owner only owner only LITERAL PROG^SEC = %102202; . . . CALL SETMODE ( PFNUM , 1 , PROG^SEC ); This LITERAL specifies that the file’s owner ID should be used by the calling process as its process access ID when the program file is run.
SETMODENOWAIT Procedure Guardian Procedure Calls (S) 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.
Guardian Procedure Calls (S) SETMODENOWAIT Procedure Syntax for TAL Programmers CALL SETMODENOWAIT ( filenum ,function ,[ param1 ] ,[ param2 ] ,[ last-params ] ,[ tag ] ); ! ! ! ! ! ! i i i i o i Parameters input filenum INT:value is a number of an open file, identifying the file to receive the SETMODENOWAIT function. input function INT:value is one of the device-dependent functions listed in Table 14-4 on page 14-68 (see SETMODE Procedure on page 14-66).
Guardian Procedure Calls (S) SETMODENOWAIT Procedure input tag INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this SETMODENOWAIT. 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.
Guardian Procedure Calls (S) SETMODENOWAIT Procedure Related Programming Manuals For programming information about the SETMODENOWAIT file-system procedure, see the Guardian Programmer’s Guide and the data communication manuals.
Guardian Procedure Calls (S) SETMYTERM Procedure (Superseded by PROCESS_SETSTRINGINFO_ SETMYTERM Procedure (Superseded by PROCESS_SETSTRINGINFO_ 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.
Guardian Procedure Calls (S) SETMYTERM Procedure (Superseded by PROCESS_SETSTRINGINFO_ = (CCE) indicates that the SETMYTERM is successful. > (CCG) does not return from SETMYTERM. Considerations If the caller to SETMYTERM creates any processes after the call to SETMYTERM, the new home terminal is the home terminal for those processes. SETMYTERM has no effect on any existing process created by the caller.
SETPARAM Procedure Guardian Procedure Calls (S) 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].
Guardian Procedure Calls (S) SETPARAM Procedure Parameters input filenum INT:value is the number of an open file for which special information is sent. input function INT:value is one of the following 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.
SETPARAM Procedure Guardian Procedure Calls (S) input param-array INT:ref:* is a list or string as required by function. input param-count INT:value is the number of bytes contained in param-array. output last-param-array INT:ref:* returns previous parameter settings associated with function. output last-param-count INT:ref:1 returns the length in bytes of the data placed into last-param-array. input last-param-max INT:value is the maximum number of bytes that can be placed in last-param-array.
SETPARAM Procedure Guardian Procedure Calls (S) [1] [2] [3] equivalent to parameter 2 of SETMODE 11 most significant word of the break tag least significant word of the break tag [0] 0, disable BREAK (default setting) 1, enable BREAK and take ownership value from last-param-array[1], return BREAK ownership to previous owner [1] Terminal access mode after BREAK is typed.
Guardian Procedure Calls (S) SETPARAM Procedure Example CALL SETPARAM ( FNUM , 8 , , , OLD^PARAMS , OLD^SIZE ); The above example fetches the protocol ID field in the outgoing call request packet. Four bytes of data return. Related Programming Manuals For programming information about the SETPARAM procedure, see the data communication manuals.
SETSTOP Procedure Guardian Procedure Calls (S) SETSTOP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) • • 2 SETSTOP Procedure A process whose process access ID = this process’s creator access ID (CAID) or the CAID group manager A process whose process access ID = this process’s process access ID (PAID) or the PAID group manager (this includes the caller to STEPMOM) unstoppable by any other process. This mode is available only when the caller of SETSTOP is privileged.
SETSYNCINFO Procedure (Superseded by FILE_SETSYNCINFO_ Procedure) Guardian Procedure Calls (S) 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.
Guardian Procedure Calls (S) SETSYNCINFO Procedure (Superseded by FILE_SETSYNCINFO_ Procedure) Parameters input filenum INT:value is the number of an open file that identifies the file whose synchronization block is being passed. input sync-block INT:ref:* is the latest synchronization block received from the primary process. Condition Code Settings < (CCL) indicates that an error occurred (call FILE_GETINFO_ or FILEINFO). = (CCE) indicates that SETSYNCINFO is successful.
SETSYSTEMCLOCK Procedure Guardian Procedure Calls (S) SETSYSTEMCLOCK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Automatically Adjusting the Clock Using Modes 0,1,2,3,6 Setting the Clock Using Modes 5 and 7 Stopping Clock Adjustment Types of Timestamps Condition Code Settings Timing and Processes System Clock System Message Example Related Programming Manual Summary The SETSYSTEMCLOCK procedure allows you to change the system clock if you are a member of the super gro
SETSYSTEMCLOCK Procedure Guardian Procedure Calls (S) Parameters input julian-gmt FIXED:value is the Julian timestamp. input mode INT:value specifies the mode and source as follows: Mode Source Action 0 Conditionally adjust to absolute Greenwich mean time (GMT) operator input If the clock error is less than or equal to two minutes, the system adjusts the clock. Otherwise the system sets the clock.
Guardian Procedure Calls (S) SETSYSTEMCLOCK Procedure timestamp. This mode is used for precise time synchronization with a hardware clock or for a moderately precise method of operator time adjustment. input tuid INT:value is a time update ID obtained from the JULIANTIMESTAMP procedure. It should be used with mode 2 and 3 to avoid conflicting changes.
Guardian Procedure Calls (S) SETSYSTEMCLOCK Procedure Stopping Clock Adjustment • • • If you call SETSYSTEMCLOCK with the mode parameter set to 8, the system stops any ongoing adjustment. If you call SETSYSTEMCLOCK twice in less than ten seconds, the system stops any ongoing adjustment and sets the clock. HP reserves the right to change, with proper customer notification, the characteristics of system clock setting and adjustment.
Guardian Procedure Calls (S) SETSYSTEMCLOCK Procedure System Clock System Message • The SETTIME system message (-10) is delivered to the calling process if the MONITORNEW procedure has enabled it. Example CALL SETSYSTEMCLOCK ( JULIAN^GMT , MODE , TUID ); Related Programming Manual For programming information about the SETSYSTEMCLOCK procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (S) SHIFTSTRING Procedure (Superseded by STRING_UPSHIFT_ Procedure ) 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.
Guardian Procedure Calls (S) SHIFTSTRING Procedure (Superseded by STRING_UPSHIFT_ Procedure ) input casebit INT:value specifies a value indicating whether to upshift or downshift the string: <15> 0 the procedure upshifts the string indicated, making all alphabetic characters uppercase. <15> 1 the procedure downshifts the string indicated, making all alphabetic characters lowercase.
Guardian Procedure Calls (S) SIGACTION_ Procedure 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. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
Guardian Procedure Calls (S) SIGACTION_INIT_ Procedure SIGACTION_INIT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General 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
Guardian Procedure Calls (S) -1D SIGACTION_INIT_ Procedure indicates an error. The reason for the error is given in the errno variable. Use the ERRNO_GET_ procedure to obtain the value of errno in a pTAL program. input handler PROCADDR:ref:1 specifies the action to be invoked when a signal occurs.
SIGACTION_INIT_ Procedure Guardian Procedure Calls (S) 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.
Guardian Procedure Calls (S) SIGACTION_INIT_ Procedure A pointer to a structure of type UCONTEXT_T. It contains information regarding the process context when the signal occurred. You can pass this pointer to the HIST_INIT_ procedure to get diagnostic information. • SIG_DFL Causes default signal handling to be installed. • SIG_ABORT Causes the process to be abnormally terminated when a signal occurs. Note. This action is similar to calling ARMTRAP(-1,-1) for a TNS Guardian process.
SIGACTION_RESTORE_ Procedure Guardian Procedure Calls (S) SIGACTION_RESTORE_ 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 SIGACTION_RESTORE_ procedure restores the signal-handling state saved by a previous call to the SIGACTION_SUPPLANT_ procedure.
Guardian Procedure Calls (S) SIGACTION_RESTORE_ Procedure Use the ERRNO_GET_ procedure to obtain the value of errno in a Guardian process. signal-buffer input INT .EXT:ref:(SIG_SAVE_TEMPLATE) specifies the address of a buffer in which the previous signal-handling state is saved. Considerations • • • • The SIGACTION_RESTORE_ procedure validates the buffer indicated by signal-buffer and returns an error if the buffer is invalid.
Guardian Procedure Calls (S) SIGACTION_SUPPLANT_ Procedure SIGACTION_SUPPLANT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters General Considerations Handler 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 runtime library) to take over signal handling temporarily.
SIGACTION_SUPPLANT_ Procedure Guardian Procedure Calls (S) 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. input handler PROCADDR:value specifies the action to be invoked when a signal occurs.
Guardian Procedure Calls (S) SIGACTION_SUPPLANT_ Procedure You must allocate the buffer for SIGACTION_SUPPLANT_ using the SIGSAVE_DEF DEFINE as follows: SIGSAVE_DEF ( signal-buffer ); where signal-buffer is a legal variable name. This buffer must be accessible to the callers of both SIGACTION_SUPPLANT_ and the associated SIGACTION_RESTORE_ procedure. The specified handler is installed as the action for only those nondeferrable signals that are system generated in response to run-time events.
SIGACTION_SUPPLANT_ Procedure Guardian Procedure Calls (S) and on whether the signal handler for that signal is installed by a nonprivileged caller or privileged caller of SIGACTION_SUPPLANT_ as follows: If a nondeferrable signal occurs in... • And the signal handler for that signal was installed by... Then the specified handler is activated at...
Guardian Procedure Calls (S) • SIGACTION_SUPPLANT_ Procedure UCONTEXT A pointer to a structure of type UCONTEXT_T. It contains information regarding the process context when the signal occurred. You can pass this pointer to the HIST_INIT_ procedure to get diagnostic information. • SIG_DFL Causes default signal handling to be installed for all signals. • SIG_ABORT Causes the process to be abnormally terminated when a signal occurs. Note.
SIGADDSET_ Procedure Guardian Procedure Calls (S) SIGADDSET_ Procedure SIGDELSET_ Procedure SIGEMPTYSET_ Procedure SIGFILLSET_ Procedure SIGISMEMBER_ Procedure Note. These procedures can be called only from native processes.
SIGJMP_MASKSET_ Procedure Guardian Procedure Calls (S) SIGJMP_MASKSET_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (S) SIGJMP_MASKSET_ Procedure Use the ERRNO_GET_ procedure to obtain the value of errno in a Guardian process. input,output env INT .EXT:ref:(SIGJMP_BUF_TEMPLATE) contains the address of a jump buffer containing context saved by the SETJMP_ or SIGSETJMP_ procedure to be restored by a subsequent call to the SIGLONGJMP_ procedure. input signal-mask INT .EXT:ref:(SIGSET_T) If not NULL, points to a valid signal mask that is added to the jump buffer indicated by env.
Guardian Procedure Calls (S) SIGJMP_MASKSET_ Procedure Examples error := SIGJMP_MASKSET_ ( env, mask ); or INT .EXT NULL := 0D; ... error := SIGJMP_MASKSET_ ( env, NULL); Related Programming Manual For programming information about the SIGJMP_MASKSET_ procedure, see the Guardian Programmer’s Guide.
SIGLONGJMP_ Procedure Guardian Procedure Calls (S) 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.
Guardian Procedure Calls (S) SIGLONGJMP_ Procedure specifies the value to be returned at the destination of the long jump; that is, at the location of the corresponding SIGSETJMP_ call. If this value is set to 0D, then 1D is returned; otherwise value is returned. 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.
Guardian Procedure Calls (S) SIGLONGJMP_ Procedure between calls to SIGSETJMP_ and SIGLONGJMP_. Alternatively, you can make the variables global. Example SIGLONGJMP_ ( env, value ); Related Programming Manual For programming information about the SIGLONGJMP_ procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (S) SIGNAL_ Procedure 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. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
Guardian Procedure Calls (S) SIGNALPROCESSTIMEOUT Procedure SIGNALPROCESSTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Message OSS Considerations 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.
Guardian Procedure Calls (S) SIGNALPROCESSTIMEOUT Procedure specifies the time period, in 0.01-second units, after which a timeout message should be queued on $RECEIVE. This value must be greater than 0D. input param1 INT:value identifies the timeout message read from $RECEIVE. input param2 INT(32):value identifies the timeout message read from $RECEIVE (same purpose as param1). output tag INT:ref:1 returns an identifier associated with the timer.
Guardian Procedure Calls (S) • SIGNALPROCESSTIMEOUT Procedure Deadlock possibility Consider the following: CALL SIGNALPROCESSTIMEOUT (10000D,,,TAG); CALL READ (REC^NUM, BUFFER, 4); . . ! open number of $RECEIVE. The read causes the process to stop and wait for the system message to be generated by timeout (assuming no other messages are expected). Timeout does not occur because process time does not advance while the read is waiting, so a deadlock occurs. Note.
SIGNALTIMEOUT Procedure Guardian Procedure Calls (S) SIGNALTIMEOUT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Message OSS Considerations 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.
Guardian Procedure Calls (S) SIGNALTIMEOUT Procedure specifies the time period, in 0.01-second units, after which a timeout message should be queued on $RECEIVE. This value must be greater than 0D. input param1 INT:value identifies the timeout message read from $RECEIVE. input param2 INT(32):value identifies the timeout message read from $RECEIVE (same purpose as param1). output tag INT:ref:1 returns an identifier associated with the timer.
Guardian Procedure Calls (S) SIGNALTIMEOUT Procedure system time; it also varies slightly from processor to processor, because all the processor clocks typically run at slightly different speeds. System time is determined by taking the average of all the processor times in the system. When measuring short intervals of time, the difference between processor time and system time is negligible. However, when measuring long intervals of time (such as several hours or more), the difference can be noticeable.
Guardian Procedure Calls (S) SIGNALTIMEOUT Procedure Related Programming Manual For programming information about the SIGNALTIMEOUT procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (S) SIGPENDING_ Procedure 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. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
Guardian Procedure Calls (S) SIGPROCMASK_ Procedure 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. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
SIGSETJMP_ Procedure Guardian Procedure Calls (S) SIGSETJMP_ 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 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.
Guardian Procedure Calls (S) SIGSETJMP_ Procedure < > 0D indicates that SIGSETJMP_ is returning as a result of a call to the SIGLONGJMP_ procedure. The returned value is specified by SIGLONGJMP_. output env INT .EXT:ref:(SIGJMP_BUF_TEMPLATE) indicates the address of a previously allocated jump buffer in which the process context of the caller is returned. The jump buffer is allocated by the SIGJMP_BUF_DEF DEFINE.
Guardian Procedure Calls (S) SIGSETJMP_ Procedure Example sigjmp_buf env; SIGJMP_BUF_DEF_ ( env ); retval := SIGSETJMP_ ( env, value ); Related Programming Manual For programming information about the SIGSETJMP_ procedure, see the Guardian Programmer’s Guide.
Guardian Procedure Calls (S) SIGSUSPEND_ 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. See the $SYSTEM.SYSTEM.HSIGNAL header file for the pTAL prototype definitions.
SSIDTOTEXT Procedure Guardian Procedure Calls (S) SSIDTOTEXT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary Converts internal format subsystem ID to external representation. 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.
SSIDTOTEXT Procedure Guardian Procedure Calls (S) chars STRING .EXT:ref:* contains the resulting displayable representation of ssid. The length of the string is returned in len. The string will not be longer than 23 characters. status INT(32) .EXT:ref:1 contains a status code describing any problem encountered. The codes in the following list are obtained by examining the two halves of the INT(32) value. (0,0) - No error. (0,x) - problem with calling sequence.
SSIDTOTEXT Procedure Guardian Procedure Calls (S) version is either a string of digits which represents a TOSVERSION-format version (Ann) or a value from 0 to 65535. Examples: HP.PATHWAY.C00 HP.52.0 0.0.0 The 0.0.0 form is used to represent the “null” subsystem ID. Its internal representation is binary zero. The number of zeros in each field may vary; for example, 000.0.000 is equivalent to 0.0.0.
Guardian Procedure Calls (S) STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Messages OSS Considerations Example Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) Guardian Procedure Calls (S) Parameters input process-id INT:ref:4 is a 4-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 4-word array, where: [0:2] [3].<0:3> .<4:7> .
Guardian Procedure Calls (S) STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) If a single named process is adopted, the caller becomes both the mom and the ancestor and will receive two process termination messages when the process dies. • STEPMOM and high-PIN processes You cannot use STEPMOM to adopt a high-PIN process because a high PIN cannot fit into process-id. Figure 14-1 illustrates the effect of STEPMOM.
STEPMOM Procedure (Superseded by PROCESS_SETINFO_ Procedure ) Guardian Procedure Calls (S) Example CALL STEPMOM ( STEP^SON ); Figure 14-1. Effect of STEPMOM (A) Creates (B) : (A) (B) MOM = (A) (B) Creates (C) : (A) (B) (C) MOM = (A) MOM = (B) (C) Calls STEPMOM and passes (B)'s process ID (A) (B) (C) MOM = (C) MOM = (B) (B) receives a process deletion message if (C) is deleted. Likewise, (C) receives a process deletion message if (B) is deleted. VST004.
Guardian Procedure Calls (S) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations NetBatch Considerations Messages OSS Considerations Examples Related Programming Manual Summary Note. This procedure is supported for compatibility with previous software and should not be used for new development.
STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) Guardian Procedure Calls (S) Syntax for C Programmers This procedure does not have a C syntax, because it is superseded and should not be used for new development. This procedure is supported only for compatibility with previous software.
Guardian Procedure Calls (S) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) output error INT:ref:1 returns a file-system error number. STOP returns a nonzero value for this parameter only when it cannot successfully make the request to stop the designated process. If it makes the request successfully (error is 0), the designated process might or might not be stopped depending on the stopmode of the process and the authority of the caller.
Guardian Procedure Calls (S) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) input length INT:value is the text length in bytes. Maximum is 80 bytes. input text STRING .EXT:ref:length is an optional string of ASCII text to be sent in the STOP system message. Condition Code Settings A condition code value is returned only when a process is calling STOP on another process and that other process could not be stopped.
Guardian Procedure Calls (S) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) If the process is a remote process running on this node and the request to stop it is from a local process on this node, then the following user IDs or associated processes may stop the process: • • • local super ID the process’s creator access ID (CAID) or the group manager of the CAID the process’s process access ID (PAID) or the group manager of the PAID If the process is a remote process on this node and the request
Guardian Procedure Calls (S) STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) that it 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.
STOP Procedure (Superseded by PROCESS_STOP_ Procedure ) Guardian Procedure Calls (S) OSS Considerations • When an OSS process is stopped by the STOP 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.
Guardian Procedure Calls (S) STRING_UPSHIFT_ Procedure STRING_UPSHIFT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Related Programming Manual Summary The STRING_UPSHIFT_ procedure changes all the alphabetic characters in a string to upper case. Nonalphabetic characters remain unchanged.
Guardian Procedure Calls (S) STRING_UPSHIFT_ Procedure out-string:maxlen output:input STRING .EXT:ref:*, INT:value returns the resultant string. The same buffer can be used for in-string and out-string. maxlen is the length in bytes of the string variable out-string. maxlen must be at least as large as the length of the input string.
SUSPENDPROCESS Procedure (Superseded by PROCESS_SUSPEND_ Guardian Procedure Calls (S) SUSPENDPROCESS Procedure (Superseded by PROCESS_SUSPEND_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
SUSPENDPROCESS Procedure (Superseded by PROCESS_SUSPEND_ Guardian Procedure Calls (S) .<8:15> PIN assigned by the operating system to identify the process in the processor If process-id[0:2] references a process pair and process-id[3] is specified as -1, then both members of the process pair are suspended. Condition Code Settings < (CCL) indicates that SUSPENDPROCESS failed, or no process designated process-id exists. = (CCE) indicates that process-id is suspended.
Guardian Procedure Calls (S) SYSTEMENTRYPOINT_RISC_ Procedure SYSTEMENTRYPOINT_RISC_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Example Summary Note. 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.
Guardian Procedure Calls (S) SYSTEMENTRYPOINT_RISC_ Procedure is the length, in bytes, of name.
Guardian Procedure Calls (S) SYSTEMENTRYPOINTLABEL Procedure SYSTEMENTRYPOINTLABEL Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 15-1 lists all the procedures in this section. Table 15-1.
TAKE^BREAK Procedure Guardian Procedure Calls (T-V) TAKE^BREAK Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The TAKE^BREAK procedure enables BREAK monitoring for a file. TAKE^BREAK is a sequential I/O (SIO) procedure and should be used only with files that have been opened by OPEN^FILE.
Guardian Procedure Calls (T-V) TAKE^BREAK Procedure Although the operating system allows a process to own BREAK on an arbitrary number of terminals, SIO supports BREAK ownership for only one terminal at a time. • • SIO does not support “break access”; SIO always issues SETMODE 11 with parameter 2 = 0. Taking BREAK ownership back If a process launches an offspring process that takes BREAK ownership, and the parent process then calls CHECK^BREAK, SIO takes BREAK ownership back.
TEXTTOSSID Procedure Guardian Procedure Calls (T-V) TEXTTOSSID Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Summary TEXTTOSSID 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. Syntax for C Programmers Note.
Guardian Procedure Calls (T-V) TEXTTOSSID Procedure is the string containing the external representation of a subsystem ID. The number of characters scanned is returned as len. See “Considerations” for the description of the external form of a subsystem ID.
Guardian Procedure Calls (T-V) TEXTTOSSID Procedure output ssid INT .EXT:ref:6 receives the internal form of the subsystem ID contained in chars. output status INT(32) .
Guardian Procedure Calls (T-V) TEXTTOSSID Procedure Considerations The external form of a subsystem ID is: owner.ss.version or 0.0.0 owner is 1 to 8 letters, digits, or hyphens, the first of which must be a letter; letters are not upshifted so the end user must enter owner in the proper case. ss is either the subsystem number or the subsystem name. A subsystem number is a string of digits which may be preceded by a minus sign. The value of the number must be between -32767 and 32767.
TIME Procedure Guardian Procedure Calls (T-V) TIME Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Related Programming Manual Summary The TIME procedure provides the current date and time in integer form.
TIMER_START_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (T-V) TIMER_START_ Procedure (H-Series RVUs Only) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (T-V) TIMER_STOP_ Procedure (H-Series RVUs Only) timeoutValue or TOV input long long a value greater than zero that specifies the time period (in microseconds) after which a timeout message should be queued on $RECIEVE. One second equals 1,000,000 microseconds.
TIMER_STOP_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (T-V) Summary The TIMER_STOP_ procedure stops a timer started using the TIMER_START_ procedure.
Guardian Procedure Calls (T-V) TIMESTAMP Procedure TIMESTAMP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Considerations Example Related Programming Manual Summary The TIMESTAMP procedure provides the internal form of the processor interval clock where the application is running.
Guardian Procedure Calls (T-V) TIMESTAMP Procedure Procedures that work with the 48-bit timestamp are CONTIME, TIME, and TIMESTAMP. • 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.
TOSVERSION Procedure Guardian Procedure Calls (T-V) TOSVERSION Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameter Example Summary The TOSVERSION procedure identifies which version of the operating system is running.
Guardian Procedure Calls (T-V) TS_NANOSECS_ Procedure (H-Series RVUs Only) For example, if the operating-system version is D10, the returned value contains “N” in bits <0:7> and binary 10 in bits <8:15>. TS_NANOSECS_ Procedure (H-Series RVUs Only) Summary Syntax for C Programmers Syntax for TAL Programmers Consideration Summary The TS_NANOSECS_ procedure returns a value that represents the time (in nanoseconds) since the last coldload.
TS_UNIQUE_COMPARE_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (T-V) Summary The TS_UNIQUE_COMPARE_ procedure compares two unique timestamps created using TS_UNIQUE_CREATE_ Procedure (H-Series RVUs Only) 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.
TS_UNIQUE_COMPARE_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (T-V) Return Value Definition TS_AMBIGUOUS [3] The values for TS1 and TS2 are nearly identical. This value is returned when TS1 and TS2 are created on the same system, but not the same CPU. If TS1 and TS2 are created on different systems, the difference in their creation time is less than one minute. TS_PROBABLY_LESS_THAN [4] The value of TS1 is probably less than the value of TS2.
Guardian Procedure Calls (T-V) TS_UNIQUE_CONVERT_TO_JULIAN_ Procedure (H-Series RVUs Only) TS_UNIQUE_CONVERT_TO_JULIAN_ Procedure (H-Series RVUs Only) Summary Syntax for C Programmers Syntax for TAL Programmers Parameter 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.
TS_UNIQUE_CREATE_ Procedure (H-Series RVUs Only) Guardian Procedure Calls (T-V) 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.
UNLOCKFILE Procedure 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.
Guardian Procedure Calls (T-V) UNLOCKFILE Procedure input tag INT(32):value is for nowait I/O only. tag is a value you define that 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.
Guardian Procedure Calls (T-V) UNLOCKFILE Procedure Example CALL UNLOCKFILE ( SAVE^FILENUM ); Related Programming Manual For programming information about the UNLOCKFILE file-system procedure, refer to the Enscribe Programmer’s Guide and the Guardian Programmer’s Guide.
UNLOCKREC Procedure Guardian Procedure Calls (T-V) 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.
Guardian Procedure Calls (T-V) UNLOCKREC Procedure Parameters input filenum INT:value is the number of an open file that identifies the file containing the record to be unlocked. input tag INT(32):value is for nowait I/O only. tag is a value you define that uniquely identifies the operation associated with this UNLOCKREC. Note. The system stores this tag value until the I/O operation completes.
Guardian Procedure Calls (T-V) • UNLOCKREC Procedure Unlocking several records If several records need to be unlocked, the UNLOCKFILE procedure can be called to unlock all records currently locked by the user (rather than unlocking the records through individual calls to UNLOCKREC). • Current-state indicators after UNLOCKREC For key-sequenced, relative, and entry-sequenced files, the current-state indicators after an UNLOCKREC remain unchanged.
UNPACKEDIT Procedure Guardian Procedure Calls (T-V) UNPACKEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Consideration 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.
Guardian Procedure Calls (T-V) UNPACKEDIT Procedure packed-length input INT:value specifies the length in bytes of packed-line. The packed-length must be in the range 1 through 256. 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.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure USER_AUTHENTICATE_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (T-V) • USER_AUTHENTICATE_ Procedure CEXTDECS (via 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.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure 70 Continue dialog. See the status parameter for detailed information on how to set the inputtext parameter in the next call to USER_AUTHENTICATE_. 160 Invalid dialog-id parameter, invalid protocol, or dialog has exceeded two minutes. 563 The text to be returned in the displaytext parameter is longer than the length specified by the displaytext-maxlen parameter. 590 Two or more parameters provided are incompatible.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure <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 Guardian user ID. When Safeguard software is running, the user can log on specifying either a member name or an alias.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure dialog) is returned on each such call along with a status value that indicates the next required piece of information. The default value is 0F. If dialog-id is not passed to USER_AUTHENTICATE_, then dialogs that require more than one call to USER_AUTHENTICATE_ are not possible. Error 48 (security violation) is returned instead of error 70. On return, status contains the same value as would have been returned with error 70.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure output status INT .EXT:ref:1 returns a value providing more information when error is 0, 48, or 70. status values are described in the following three tables: Values returned for error = 0 (no error): status Description 0 No status. 8 Password is valid but it is about to expire. Caller should return caution message. Values returned for error = 48 (security violation): status Description 1 User does not exist or password is incorrect.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure status Description 16 Password change request: new password does not conform to password quality. New password is rejected. 17 Password change request: new password contains blank characters. New password is rejected. 18 Password change request: new password is not verified. The first new password provided is not the same as the second new password provided. 19 Password change request: change cannot made during the allowed time period.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure aligned. The last line of text is followed by a byte length of 0 to indicate that there are no more display lines. Display text, generated by $CMON or Safeguard software, can be returned anytime during a dialog. displaytext-maxlen is a value in the range 0 through 256. This parameter pair is required if displaytext-len is specified. displaytext-len output INT .EXT:ref:1 if displaytext is returned, contains its actual length in bytes.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure This parameter is required if volsubvol:volsubvol-maxlen is specified. initdir:initdir-maxlen output:input STRING .EXT:ref:*, INT:value if present and if initdir-maxlen is not 0, returns the OSS pathname for the initial working directory for the specified user in an OSS environment. initdir-maxlen specifies the length of the string variable initdir in bytes. This parameter pair is required if initdir-len is specified.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure 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. If either the password cannot be changed at the time USER_AUTHENTICATE_ is called or the password has no expiration date, 0F is returned.
USER_AUTHENTICATE_ Procedure Guardian Procedure Calls (T-V) During a dialog, inputtext can specify the information in multiple calls. The following example shows how inputtext could be set in three successive calls: 1. inputtext 2. inputtext 3.
Guardian Procedure Calls (T-V) • USER_AUTHENTICATE_ Procedure Incorrect password timeout When Safeguard software is running, the number of times that a process can pass an invalid password to USER_AUTHENTICATE_ before the process is suspended and the length of time that the process is suspended are set during Safeguard configuration. When Safeguard software is not running, any process that passes an invalid password to USER_AUTHENTICATE_ for the third time is suspended for 60 seconds.
Guardian Procedure Calls (T-V) USER_AUTHENTICATE_ Procedure user that logon is denied due to password expiration. Another application could continue the dialog and prompt for a new password sequence. Related Programming Manuals For programming information on the command-interpreter monitor process ($CMON), refer to the Guardian Programmer’s Guide. For more information on the Safeguard product, refer to the Safeguard Reference Manual.
Guardian Procedure Calls (T-V) USER_GETINFO_ Procedure USER_GETINFO_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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 C Programmers Note. In the TNS/E environment the CEXTDECS file uses the int data type for 32-bit values.
Guardian Procedure Calls (T-V) USER_GETINFO_ Procedure Syntax for TAL Programmers error := USER_GETINFO_ ( [ user-name:user-maxlen ] i,o:i ,[ 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 ] ); ! ! ! ! ! ! ! ! ! ! ! ! ! ! i,o i,o o o o o o:i o o:i o o:i o o Parameters returned value error INT r
Guardian Procedure Calls (T-V) USER_GETINFO_ Procedure user-name:user-maxlen input, output:input STRING .EXT:ref:*, INT:value on input, if present and if user-curlen is not 0, specifies the user name or alias for which the default information is to be returned. On output, if user-id is specified, this parameter returns the corresponding user name; otherwise, it remains unchanged from input. user-name is passed, and returned, in one of two forms: groupname.
Guardian Procedure Calls (T-V) USER_GETINFO_ Procedure output is-alias INT .EXT:ref:1 indicates whether a user name or an alias is supplied in user-name. This parameter returns the following values: -1 user-name is an alias. 0 user-name is a user name. output group-count INT .EXT:ref:1 returns the number of groups to which the specified user belongs. group-count is the number of valid elements in group-list. output group-list INT(32) .
Guardian Procedure Calls (T-V) USER_GETINFO_ Procedure initdir:initdir-maxlen output:input STRING .EXT:ref:*, INT:value if present and if initdir-maxlen is not 0, returns the OSS pathname for the initial working directory for the specified user in an OSS environment. initdir-maxlen specifies the length of the string variable initdir in bytes. This parameter pair is required if initdir-len is specified. output initdir-len INT .EXT:ref:1 if initdir is returned, contains its actual length in bytes.
Guardian Procedure Calls (T-V) 3 4 5 6 7 USER_GETINFO_ Procedure not used N (any network user) C (any network group/community user) U (only the network owner) - (only the local super ID) Considerations • • Either user-id or user-name must be supplied. If both parameters are supplied and user-curlen is greater than zero, then user-name is used and user-id is treated as an output parameter. In this case, no attention is paid to the current contents of the user-id parameter.
USER_GETNEXT_ Procedure Guardian Procedure Calls (T-V) USER_GETNEXT_ Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (T-V) 590 USER_GETNEXT_ Procedure Bad parameter value. Either the value specified in user-curlen is greater than the value specified in user-maxlen or the value specified in user-curlen is not within the valid range. Refer to the Guardian Procedure Errors and Messages Manual for more information on file-system error messages. user-name:user-maxlen input, output:input STRING .
Guardian Procedure Calls (T-V) USER_GETNEXT_ Procedure Considerations • • • • Aliases are defined only when Safeguard software is installed. This procedure returns a user name when is-alias is set to 0 on input and when is-alias returns 0 on output. This procedure returns an alias when is-alias is not set to 0. When the names are returned, user names are returned first and aliases are returned last. Furthermore, the return sequence is not circular: a user name never follows an alias.
USERDEFAULTS Procedure (Superseded by USER_GETINFO_ Procedure ) Guardian Procedure Calls (T-V) USERDEFAULTS Procedure (Superseded by 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.
Guardian Procedure Calls (T-V) 29 USERDEFAULTS Procedure (Superseded by USER_GETINFO_ Procedure ) Missing parameter. This procedure was called without specifying one of the required parameters (either user-id or user-name). Refer to the Guardian Procedure Errors and Messages Manual for more information on file-system error messages. input user-id STRING .EXT:ref:2 specifies the user ID for which the default information is to be retrieved.
Guardian Procedure Calls (T-V) USERDEFAULTS Procedure (Superseded by USER_GETINFO_ Procedure ) <10:12> execute <13:15> purge where the legitimate fields are encoded with numbers that represent the following information: 0 1 2 3 4 5 6 7 A (any local user) G (any local group member) O (only the local owner) not used N (any network user) C (any network group/community user) U (only the network owner) - (only the local super ID) Condition Code Settings = (CCE) indicates that the default information is retu
Guardian Procedure Calls (T-V) BEGIN . .
USERIDTOUSERNAME Procedure (Superseded by USER_GETINFO_ Procedure ) Guardian Procedure Calls (T-V) USERIDTOUSERNAME Procedure (Superseded by USER_GETINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
USERIOBUFFER_ALLOW_ Procedure Guardian Procedure Calls (T-V) id-name[4] FOR 4 member name, blank-filled Condition Code Settings < (CCL) indicates that id-name is out of bounds or that an I/O error occurred with the $SYSTEM.SYSTEM.USERID file. = (CCE) indicates that the designated user name returned. > (CCG) indicates that the specified user ID is undefined.
USERNAMETOUSERID Procedure (Superseded by USER_GETINFO_ Procedure ) Guardian Procedure Calls (T-V) USERNAMETOUSERID Procedure (Superseded by USER_GETINFO_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
USERNAMETOUSERID Procedure (Superseded by USER_GETINFO_ Procedure ) Guardian Procedure Calls (T-V) name-id.<0:7> name-id.<8:15> group ID {0:255} member ID {0:255} Condition Code Settings < (CCL) indicates that name-id is out of bounds or that an I/O error occurred with the $SYSTEM.SYSTEM.USERID file. = (CCE) indicates that the designated user ID returned. > (CCG) indicates that the specified user name is undefined.
Guardian Procedure Calls (T-V) USESEGMENT Procedure (Superseded by SEGMENT_USE_ Procedure ) USESEGMENT Procedure (Superseded by SEGMENT_USE_ 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.
Guardian Procedure Calls (T-V) USESEGMENT Procedure (Superseded by SEGMENT_USE_ Procedure ) Syntax for TAL Programmers old-segment-id := USESEGMENT [ ( segment-id ) ]; ! i Parameters old-segment-id returned value INT returns the segment ID of the previously used selectable segment, if any; otherwise, it returns -1. If segment-id specifies a flat segment, old-segment-id returns the segment ID of the current in-use selectable segment.
Guardian Procedure Calls (T-V) VRO_SET_ Procedure (H-Series RVUs Only) Example INT seg^id1 := 0; INT seg^id2 := 1; INT old^seg^id; INT status; INT(32) seg^len := %177777D; status := IF status status := IF status ! 64K - 1 bytes ALLOCATESEGMENT ( seg^id1, seg^len ); <> 0 THEN ... ALLOCATESEGMENT ( seg^id2, seg^len ); <> 0 THEN ... old^seg^id := USESEGMENT ( seg^id1 ); IF <> THEN ... old^seg^id := USESEGMENT ( seg^id2 ); IF <> THEN ...
VERIFYUSER Procedure (Superseded by USER_AUTHENTICATE_ Guardian Procedure Calls (T-V) 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.
VERIFYUSER Procedure (Superseded by USER_AUTHENTICATE_ Guardian Procedure Calls (T-V) Parameters input user-name-or-id INT:ref:12 is an array containing the name or user ID of the user to be verified or logged on, as follows: [0:3] [4:7] group name, blank-filled member name, blank-filled The group name and member name must both be input in uppercase. or [0].<0:7> group ID [0].
Guardian Procedure Calls (T-V) VERIFYUSER Procedure (Superseded by USER_AUTHENTICATE_ where the legitimate fields are encoded with numbers that represent the following information: 0 A (any local user) 1 G (any local group member) 2 O (only the local owner) 3 not used 4 N (any network user) 5 C (any network group/community user) 6 U (only the network owner) 7 - (only the local super ID) input default-len INT:value is the length, in bytes, of the default array.
Guardian Procedure Calls (T-V) • • • • VERIFYUSER Procedure (Superseded by USER_AUTHENTICATE_ Following a successful logon with this procedure, the calling process is considered local with respect to the system on which it is running. A process that passes an invalid password to VERIFYUSER for the third time is suspended for 60 seconds. Note that each call to VERIFYUSER always results in an open, KEYPOSITION, READUPDATEUNLOCK, WRITEUPDATEUNLOCK, and close operation on the USERID file.
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 16-1 lists all the procedures in this section. Table 16-1.
Guardian Procedure Calls (W-Z) WAIT^FILE Procedure WAIT^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (W-Z) WAIT^FILE Procedure Syntax for TAL Programmers error := WAIT^FILE ( file-fcb ,[ count-read ] ,[ time-limit ] ); ! i ! o ! i Parameters returned value error INT If abort-on-error mode is in effect, the only possible values for error are: 0 1 6 40 111 532 No error End of file System message (only if user requested system messages through SET^SYSTEMMESSAGES or SET^SYSTEMMESSAGESMANY) Operation timed out (only if time-limit is supplied and is not -1D) Operation aborts becau
WAIT^FILE Procedure Guardian Procedure Calls (W-Z) there is a completion. If no completion occurs the I/O operation is still outstanding; an error 40 and an “operation timed out” message are returned. 0D (and error = 40) -1D There is no completion. Therefore, READ^FILE or WRITE^FILE cannot be called for the file until the operation completes by WAIT^FILE. indicates a willingness to wait forever.
Guardian Procedure Calls (W-Z) WRITE[X] Procedures WRITE[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Disk File Considerations Interprocess Communication Consideration Considerations for WRITEX Only 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”).
WRITE[X] Procedures Guardian Procedure Calls (W-Z) Syntax for TAL Programmers CALL WRITE[X] ( filenum ,buffer ,write-count ,[ count-written ] ,[ tag ] ); ! ! ! ! ! i i i o i Parameters input filenum INT:value (Use with WRITE and WRITEX) is the number of an open file that identifies the file to be written. input buffer INT:ref:* (Use with WRITE) STRING .EXT:ref:* (Use with WRITEX) is an array containing the information to be written to the file.
Guardian Procedure Calls (W-Z) WRITE[X] Procedures input tag INT(32):value (Use with WRITE and WRITEX) 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.
WRITE[X] Procedures Guardian Procedure Calls (W-Z) You should not change the contents of the data buffer between the initiation and completion of a nowait write operation. This is because a retry can copy the data again from the user buffer and cause the wrong data to be written. You should avoid sharing a buffer between a write and another I/O operation because this creates the possibility of changing the contents of the write buffer before the write is completed.
Guardian Procedure Calls (W-Z) WRITE[X] Procedures 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.
Guardian Procedure Calls (W-Z) WRITE[X] Procedures For relative and entry-sequenced files, the current position is that of the record just inserted and the current primary-key value is set to the value of the record’s primary key. • Duplicate record found on insertion request When attempting to insert a record into a key-sequenced file, if a duplicate record is found, the WRITE[X] procedure returns error 10 (record already exists) or error 71 (duplicate record).
Guardian Procedure Calls (W-Z) WRITE[X] Procedures Interprocess Communication Consideration • Indication that the destination process is running If the WRITE[X] is to another process, successful completion of the WRITE[X] (or AWAITIO[X] if nowait) indicates that the destination process is running. Considerations for WRITEX Only • • • • • • • • The buffer and count transferred may be in the user stack or in an extended data segment. The buffer and count transferred cannot be in the user code space.
Guardian Procedure Calls (W-Z) WRITE[X] Procedures Example CALL WRITE ( OUT^FILE , OUT^BUFFER , 72 ); Related Programming Manuals For programming information about the WRITE file-system procedure, refer to the Guardian Programmer’s Guide, the Enscribe Programmer’s Guide, and the data communication manuals.
Guardian Procedure Calls (W-Z) WRITE^FILE Procedure WRITE^FILE Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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.
Guardian Procedure Calls (W-Z) 111 WRITE^FILE Procedure Operation aborted because of BREAK (if BREAK is enabled) If nowait is not 0, the only possible value for error is 0, when abort-on-error mode is in effect. input file-fcb INT:ref:* identifies the file to which data is written. input buffer INT:ref:* is the data to be written. buffer must be located within ‘G’[ 0:32767 ], the process data area. input write-count INT:value is the count of the number of bytes of buffer to be written.
Guardian Procedure Calls (W-Z) WRITE^FILE Procedure Example CALL WRITE^FILE ( OUT^FILE, BUFFER, COUNT ); Related Programming Manual For programming information about the WRITE^FILE procedure, refer to the Guardian Programmer’s Guide.
Guardian Procedure Calls (W-Z) WRITEEDIT Procedure WRITEEDIT Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_. Syntax for C Programmers Note.
Guardian Procedure Calls (W-Z) WRITEEDIT Procedure returns a file-system error number indicating the outcome of the operation. Possible values include: 10 File already includes a line with the specified record number. 21 Specified record is too long to fit into EDIT packed line format. (The maximum is 255 bytes of packed text.) 45 All of the file’s possible extents are allocated and full. You can use EXTENDEDIT to increase the file’s extent size and call WRITEEDIT again.
Guardian Procedure Calls (W-Z) WRITEEDIT Procedure if present and not equal to 0, specifies that all trailing space characters (if any) in the line being processed should be retained in the output line image. Otherwise, trailing space characters are discarded. new-record-number output INT(32) .EXT:ref:1 returns the record number of the newly written line. This value is 1000 times the EDIT line number of the line. Example INT(32) record^num := -2D; ! write to end of file . .
Guardian Procedure Calls (W-Z) WRITEEDITP Procedure WRITEEDITP Procedure Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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_.
Guardian Procedure Calls (W-Z) WRITEEDITP Procedure 45 All of the file’s possible extents are allocated and full. You can use EXTENDEDIT to increase the file’s extent size and call WRITEEDITP again. input filenum INT:value specifies the file number of the open file to which the line is to be written. record-number input INT(32):value if present, specifies the record number of the line to be written.
Guardian Procedure Calls (W-Z) WRITEREAD[X] Procedures 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 waits for data to be transferred back from the file.
WRITEREAD[X] Procedures Guardian Procedure Calls (W-Z) Syntax for C Programmers #include _cc_status WRITEREAD ( short filenum ,short _near *buffer ,short write-count ,short read-count ,[ short _near *count-read ] ,[ __int32_t tag ] ); #include _cc_status WRITEREADX ( short filenum ,char *buffer ,short write-count ,short read-count ,[ short *count-read ] ,[ __int32_t tag ] ); • • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typed
Guardian Procedure Calls (W-Z) WRITEREAD[X] Procedures is an array containing information to be written to the file. On return, buffer contains the information read from the file. input write-count INT:value (Use with WRITEREAD and WRITEREADX) 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.
Guardian Procedure Calls (W-Z) WRITEREAD[X] Procedures Considerations • WRITEREAD versus WRITEREADX Use WRITEREAD when the buffer has a 16-bit address, and use WRITEREADX when the buffer has a 32-bit extended address. Therefore, the data buffer for WRITEREADX can be either in the caller’s stack segment or any extended data segment. • Waited I/O READ If a waited I/O WRITEREAD[X] is executed, the count-read parameter indicates the number of bytes actually read.
Guardian Procedure Calls (W-Z) • • • • WRITEREAD[X] Procedures 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). If the file is opened for nowait I/O, the extended segment containing the buffer need not be in use at the time of the call to AWAITIOX. Nowait I/O initiated with these routines may be canceled with a call to CANCEL or CANCELREQ.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures 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.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures Syntax for C Programmers #include _cc_status WRITEUPDATE ( short filenum ,short _near *buffer ,short write-count ,[ short _near *count-written ] ,[ __int32_t tag ] ); #include _cc_status WRITEUPDATEX ( short filenum ,const char *buffer ,short write-count ,[ short *count-written ] ,[ __int32_t tag ] ); • • CEXTDECS (through the included file TNSINTH) defines 32-bit values as the typedef __int32_t w
WRITEUPDATE[X] Procedures Guardian Procedure Calls (W-Z) input write-count INT:value (Use with WRITEUPDATE and WRITEUPDATEX) is the number of bytes to be written to the file: {0:4096} for disk files (see “Disk File Considerations”) {0:32767} for magnetic tapes For key-sequenced and relative files: 0 means delete the record. For entry-sequenced files: 0 means anything <> the record’s length is invalid. output count-written INT:ref:1 INT .
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures Considerations • WRITEUPDATE versus WRITEUPDATEX Use WRITEUPDATE when the buffer has a 16-bit address, and use WRITEUPDATEX when the buffer has a 32-bit extended address. Therefore, the data buffer for WRITEUPDATEX can be either in the caller’s stack segment or any extended data segment.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures You should not change the contents of the data buffer between the initiation and completion of a nowait write operation. This is because a retry can copy the data again from the user buffer and cause the wrong data to be written. You should avoid sharing a buffer between a write and another I/O operation because this creates the possibility of changing the contents of the write buffer before the write is completed.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures the file is created, the value of write-count is rounded up to an even value before the WRITEUPDATE[X] is executed. 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.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures When WRITEUPDATE[X] is used with magnetic tape the number of bytes to be written must fit exactly; otherwise, information on the tape can be lost. However, no error indication is given. • Limitation of WRITEUPDATE[X] to the same record Five is the maximum number of times a WRITEUPDATE[X] can be executed to the same record on tape.
Guardian Procedure Calls (W-Z) WRITEUPDATE[X] Procedures Example CALL WRITEUPDATE ( TAPE^NUM , TAPE^BUF , NUM^READ , NUM^WRITTEN ); The application makes the necessary changes to the record in TAPE^BUF, then edits the tape by calling WRITEUPDATE. The tape is backspaced over the record just read, then updated by writing the new record in its place. NUM^READ indicates the number of bytes to be written (ensuring that the same number of bytes just read are also written).
Guardian Procedure Calls (W-Z) WRITEUPDATEUNLOCK[X] Procedures WRITEUPDATEUNLOCK[X] Procedures Summary Syntax for C Programmers Syntax for TAL Programmers Parameters Condition Code Settings Considerations Considerations for WRITEUPDATEUNLOCKX Only Errors for WRITEUPDATEUNLOCKX Only OSS Considerations Example Related Programming Manuals Summary The WRITEUPDATEUNLOCK[X] procedures perform random processing of records in a disk file.
Guardian Procedure Calls (W-Z) WRITEUPDATEUNLOCK[X] Procedures Syntax for C Programmers #include _cc_status WRITEUPDATEUNLOCK ( short filenum ,short _near *buffer ,short write-count ,[ short _near *count-written ] ,[ __int32_t tag ] ); #include _cc_status WRITEUPDATEUNLOCKX ( short filenum ,const char *buffer ,short write-count ,[ short *count-written ] ,[ __int32_t tag ] ); • • CEXTDECS (through the included file TNSINTH) defines 32-bit val
WRITEUPDATEUNLOCK[X] Procedures Guardian Procedure Calls (W-Z) input write-count INT:value (Use with WRITEUPDATEUNLOCK and WRITEUPDATEUNLOCKX) is the number of bytes to be written to the file: {0:4096}. For key-sequenced and relative files For entry-sequenced files 0 deletes the record 0 is illegal (error 21) output count-written INT:ref:1 INT .EXT:ref:1 (Use with WRITEUPDATEUNLOCK) (Use with WRITEUPDATEUNLOCKX) is for wait I/O only.
Guardian Procedure Calls (W-Z) WRITEUPDATEUNLOCK[X] Procedures Considerations • WRITEUPDATEUNLOCK versus WRITEUPDATEUNLOCKX Use WRITEUPDATEUNLOCK when the buffer has a 16-bit address, and use WRITEUPDATEUNLOCKX when the buffer has a 32-bit extended address. Therefore, the data buffer for WRITEUPDATEUNLOCKX can be either in the caller’s stack segment or any extended data segment.
Guardian Procedure Calls (W-Z) WRITEUPDATEUNLOCK[X] Procedures record does not exist, the call to WRITEUPDATEUNLOCK[X] is rejected with filesystem error 11. See the “Considerations” for WRITEUPDATE[X]. • Invalid write operations to queue files DP2 rejects WRITEUPDATEUNLOCK[X] operations with an error 2. Considerations for WRITEUPDATEUNLOCKX Only • • • • • • • • The buffer and count transferred may be in the user stack or in an extended data segment.
Guardian Procedure Calls (W-Z) • WRITEUPDATEUNLOCK[X] Procedures The file system cannot use the user's segment when needed. OSS Considerations • This procedure operates only on Guardian objects. If an OSS file is specified, error 2 is returned.
Guardian Procedure Calls (W-Z) XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK_ XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. XBNDSTEST aids user programs in checking stack limits and/or parameter addresses.
Guardian Procedure Calls (W-Z) -1 -2 -3 -4 XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK_ Out of bounds or illegal address Incorrectly aligned on word boundary Undefined flag value In bounds, but in an extensible extended data segment that cannot be extended (usually due to lack of additional disk space for the swap file) input param STRING .EXT:ref:* is the parameter to be bounds-checked. input bytelen INT:value is the unsigned length of the parameter, in bytes {0:65535}.
Guardian Procedure Calls (W-Z) • • XBNDSTEST Procedure (Superseded by REFPARAM_BOUNDSCHECK_ An address falling in the system library area on a native system, which now causes a status value of 1 to be returned, previously caused a status value of -1 (illegal address) to be returned. The condition that now causes a status value of -4 to be returned (address is in an extensible extended data segment that cannot be extended) previously caused a status value of -1 (illegal address) to be returned.
Guardian Procedure Calls (W-Z) XSTACKTEST Procedure (Superseded by HEADROOM_ENSURE_ XSTACKTEST Procedure (Superseded by HEADROOM_ENSURE_ Procedure ) Summary Syntax for C Programmers Syntax for TAL Programmers Parameters 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. XSTACKTEST, used with LASTADDRX and XBNDSTEST checks stack limits.
Guardian Procedure Calls (W-Z) 632 XSTACKTEST Procedure (Superseded by HEADROOM_ENSURE_ Insufficient stack space available input firstparm INT:ref:* points to the first parameter word of the first called procedure. input stackwords INT:value is the number of words required for the stack, starting from the firstparm location.
A Device Types and Subtypes Table A-1. Device Types and Subtypes (page 1 of 9) Type Device Sub type G-Series and H-Series Descriptions 0 Process 0 Default subtype for general use 1-49 Reserved for definition by HP.
Device Types and Subtypes Table A-1. Device Types and Subtypes (page 2 of 9) Type Device Sub type G-Series and H-Series Descriptions 29 N.A. 31 N.A. 33 N.A. 34 N.A.
Device Types and Subtypes Table A-1. Device Types and Subtypes (page 3 of 9) Type Device Sub type G-Series and H-Series Descriptions 11 5142 DAT with PMF or IOMF 521A, 524A, 525A (LTO) tape units (512 tracks, 7.32kb/mm) with PMF or IO 4 Magnetic 14 5 Printer 0 1 N.A. 3 4 5 N.A. 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.
Device Types and Subtypes Table A-1.
Device Types and Subtypes Table A-1.
Device Types and Subtypes Table A-1.
Device Types and Subtypes Table A-1. Device Types and Subtypes (page 7 of 9) Type Device Sub type 50 CSM 0 N.A. 1 N.A. 2 SWAN concentrator manager (CONMGR) 3 $ZZWAN WAN manager process 4 WANBOOT process 63 Subsystem Control Point (SCP) 0 Line interface unit (LIU) 1 Bisynchronous (BISYNC) point-to-point line 2 ADCCP line 3 N.A.
Device Types and Subtypes Table A-1. Device Types and Subtypes (page 8 of 9) Type Device Sub type G-Series and H-Series Descriptions 5 N.A. 6 N.A. General Device Support 57 GDS 0 58 SNAX/XF or SNAX/APN 0 1 2 N.A. 3 4 59 60 AM6520 AM3270 0 N.A. 10 N.A. 0 10 TR3271 61 X.25 Line attached to SWAN concentrator 1 11 Line attached to SWAN concentrator 0-61 N.A. 62 N.A.
Device Types and Subtypes Table A-1.
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.
Completion Codes Completion Code Definition 5 Process calls PROCESS_STOP_ (with abnormal termination specified) or ABEND on itself. This code is the default completion code for the PROCESS_STOP_ procedure (when abnormal termination is specified) and the ABEND procedure. 6 PROCESS_STOP_, STOP, or ABEND was called to delete a process by an external, but authorized, process. The system includes this completion code in the process deletion message.
Completion Codes The following completion codes are reserved for HP use: Completion Code -1 Definition 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.
Completion Codes Completion Code -6 Definition An OSS process or native process terminated when it caused a hardware exception. The termination information field of the message contains the signal number. The termination text is in the message for all processes. However, while the TACL command interpreter displays the termination text when it is present in the message for a process created by TACL, OSS utilities such as osh typically do not.
Completion Codes Completion Code Definition -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. The OSS process ID continues to exist as it migrates to another process handle, but the original process handle is deleted.
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 Names and Process Identifiers Disk File Names Disk File Names The syntax for a file name that identifies a disk file is: [node.][[volume.]subvol.]file-id or [node.][volume.]temp-file-id node specifies the name of the node on which the file resides. A node name consists of a backslash (\) followed by one to seven alphanumeric characters; the first alphanumeric character must be a letter. volume specifies the name of the volume on which the file resides.
File Names and Process Identifiers Nondisk Device Names Nondisk Device Names The syntax for a file name that identifies a nondisk device is: [node.]device-name[.qualifier] or [node.]ldev-number node specifies the name of the node on which the device resides. A node name consists of a backslash (\) followed by one to seven alphanumeric characters; the first alphanumeric character must be a letter. device-name specifies the name of a device.
File Names and Process Identifiers Process File Names for Unnamed Processes Process File Names for Unnamed Processes The syntax for a process file name that identifies an unnamed process is: [node.]$:cpu:pin:seq-no 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.
File Names and Process Identifiers Process File Names for Named Processes Process File Names for Named Processes The syntax for a process file name that identifies a named process is: [node.]process-name[:seq-no][.qual-1[.qual-2]] 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. process-name specifies the name of the process.
File Names and Process Identifiers Process Descriptors 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. The following are examples of process descriptors: \node5.$zproc:1622091078 \east.
File Names and Process Identifiers Process Handles whether the system interprets the file-name pattern according to the rules of the second or third form. As a result, the file-name pattern “$*.*” cannot match a permanent disk file name, but “*.*” can match a permanent disk file name (in the form subvol.file-id). Examples *z* matches all files in the current subvolume that have names (file IDs) containing the letter "z.
File Names and Process Identifiers C-Series Syntax C-Series Syntax This subsection summarizes the file name syntax that is supported in C-series RVUs and is still supported in the system procedures carried over from the C series. It describes both the external and internal forms of disk file names and nondisk file names. It also includes the syntax for process file names and process IDs.
File Names and Process Identifiers External File Names 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. 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.
File Names and Process Identifiers Internal File Names ldev-number specifies a logical device number. A logical device number consists of a dollar sign ($) followed by one to four digits. The logical device number 0 (represented “$0”) is reserved for the Event Management Service (EMS) collector process. qual-1 and qual-2 are optional qualifiers. qual-2 cannot be used in combination with devicename; neither qualifier can be used in combination with ldev-number.
File Names and Process Identifiers Process File Names [4:11][ qual-1 ] (with device-name only) (blank fill) To access $RECEIVE, use [0:11]“$RECEIVE” (blank fill) To access another process, if it is named, use [0:3]process-name (blank fill) [4:7][ qual-1 ] (blank fill) [8:11][ qual-2 ] (blank fill) Network File Names The internal form of a network file name is: [0].<0:7> “\” [0].
File Names and Process Identifiers Process IDs [3].<4:7> Processor in which the process resides; optional [3].<8:15> PIN assigned by the system to identify the process in the processor; optional [ qual-1 ] (blank fill) [ qual-2 ] (blank fill) [4:7] [8:11] Network Form of Process File Name The network form of a process file name is: [0].<0:7> [0].<8:15> [1:2] [3].<4:7> [3].
File Names and Process Identifiers OSS Pathname Syntax 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 limitsh 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.
OSS Pathname Syntax File Names and Process Identifiers filename. The maximum length is NAME_MAX characters, as defined in the limitsh header file (this value is 248). Examples OSS pathnames can be absolute or relative. Absolute pathnames begin with a slash (/), which indicates the root directory. The following is an example of an absolute OSS pathname: /usr/ccomp/prog1.c Relative pathnames (which do not begin with a slash) are relative to the OSS current working directory.
E DEFINEs This appendix describes DEFINEs and the attributes of the different classes of DEFINEs. Refer to the Guardian Programmer’s Guide for information about using DEFINEs programmatically. Refer to the Guardian User’s Guide for information about using DEFINEs interactively with a TACL process. 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.
DEFINE Attributes DEFINEs • When specified as the value of a procedure parameter that has a fixed length of 24 characters, a DEFINE name must be left-justified in the DEFINE name buffer and padded on the right with blanks. Uppercase and lowercase letters in a DEFINE name are equivalent. For example, the name =MY^DEFINE is equivalent to =My^Define. DEFINE Attributes A set of attributes is associated with each DEFINE. One attribute that is associated with every DEFINE is the CLASS attribute.
Available DEFINE Classes DEFINEs CLASS Attribute All DEFINEs have a special attribute called the CLASS attribute. The CLASS attribute determines which other attributes are associated with the DEFINE. The value of the CLASS attribute is a keyword; the CLASS attribute can be CATALOG, DEFAULTS, MAP, SEARCH, SORT, SPOOL, SUBSORT, TAPE, or TAPECATALOG. When assigning values to DEFINE attributes, you must assign one of these values to the CLASS attribute first.
CLASS SEARCH DEFINEs DEFINEs 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.
CLASS SPOOL DEFINEs DEFINEs CLASS SPOOL DEFINEs A CLASS SPOOL DEFINE passes information to the spooler collector process to assign values to spooler job attributes. Refer to the Spooler Utilities Reference Manual and the Spooler Plus Utilities Reference Manual for detailed information about the CLASS SPOOL DEFINE and its attributes. CLASS TAPE DEFINEs A CLASS TAPE DEFINE passes information to the tape process when using labeled magnetic tapes.
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.
Formatter Edit Descriptors • Summary of Repeatable Edit Descriptors Buffer control / Terminate the current buffer, and then obtain a new one : Terminate formatting if no data elements remain 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.
Formatter Edit Descriptors Summary of Decorations Summary of Decorations Decorations specify alphanumeric strings that can be added to a field either before basic formatting is begun or after it is finished.
Nonrepeatable Edit Descriptors Formatter Edit Descriptors Nonrepeatable Edit Descriptors The following 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 Formatter Edit Descriptors The current position can be moved beyond the limits of the current buffer (that is, become less than or equal to zero, or greater than bufferlen) without an error resulting, provided that no attempt is made by a subsequent edit descriptor to transmit data to or from a position outside the current buffer. Tab descriptors cannot be used to advance to later buffers or to return to previous ones.
Scale-Factor Descriptor (P) Formatter Edit Descriptors In a quoted literal form, if the character string to be represented contains the same character that is used as the delimiter, two consecutive characters are used to distinguish the data character from the delimiter; for example: To represent: Use: can't 'can''t' "can't" '"can''t"' or or "can't" """can't""" In the Hollerith constant form, the number of characters in the string (including blanks) must be exactly equal to the number preceding th
Optional Plus Descriptors (S, SP, SS) Formatter Edit Descriptors 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.
Buffer Control Descriptors (/, :) Formatter Edit Descriptors Buffer Control Descriptors (/, :) There are two edit descriptors used for buffer control: / indicates the end of data list item transfer on the current buffer and obtains the next buffer. The current position is moved to 1 in preparation for processing the next buffer. : indicates termination of the formatting provided there are no remaining data elements.
Repeatable Edit Descriptors Formatter Edit Descriptors The “|” character is used to denote the boundaries of the output field. Repeatable Edit Descriptors The following descriptions give the form, function, and requirements for each of the edit descriptors that specify formatting of data fields. The following edit descriptors can be preceded by an unsigned integer repeat factor to specify identical formatting for a number of values in the data list.
The A Edit Descriptor Formatter Edit Descriptors It is not mandatory that the data element be of type character. For example, an INTEGER(16) element containing the octal value %015536 corresponds to the ASCII characters “ESC” and “^”, which can be output to an ADM-2 terminal using an A2 descriptor to control a blinking field on the screen.
The B Edit Descriptor Formatter Edit Descriptors 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 the following forms: OR Bw Bw.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. After the field is processed, the current position is advanced by w characters.
The E Edit Descriptor Formatter Edit Descriptors The E Edit Descriptor The exponential edit descriptor is used to display or interpret data in floating-point form. It is usually used when data values have extremely large or extremely small magnitude. The E edit descriptor has one of the following forms: Ew.d OR Ew.dEe w an unsigned integer constant that defines the total field width (including the exponent) and cannot exceed 255.
The E Edit Descriptor Formatter Edit Descriptors On output, the field (for a scale factor of zero) appears in the following form: {[+]} [0].n n … n { - } 1 2 d E {+} e e …e {-} 1 2 e Indicates an optional plus or a minus {[+]} { - } Are the d most significant digits of the value of the data n n ... n 1 2 d after rounding E Signals the start of the decimal exponent {+} Indicates that a plus or minus is required {-} Are the e most significant digits of the exponent e e ...
The F Edit Descriptor Formatter Edit Descriptors The “|” character is used to denote the boundaries of the output field. Note. To use the E edit descriptor for output, floating-point firmware is required. The following 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 G Edit Descriptor Formatter Edit Descriptors form is used, leading zeros are supplied if needed to satisfy the requirement of m digits to the left of the decimal point. For example: Format Data Value Result F10.4 123.4567 | 123.4567| F10.4 0.000123 | 0.0001| F10.4. 3 -4.56789 | 004.5679| The “|” character is used to denote the boundaries of the output field.
The I Edit Descriptor Formatter Edit Descriptors Magnitude of Data Not Less Than Less Than Equivalent Conversion Effected 10 ** (d-2) 10 ** (d-1) F(w-n).1,n(' ') 10 ** (d-1) 10 ** F(w-n).0,n(' ') d 10 ** d Ew.d or Ew.dEe The value of n is 4 for Gw.d format and (e+2) for Gw.dEe format. The n(‘ ’) used in the above example indicates nth number of blanks. If the F form is chosen, then the scale factor is ignored.
The I Edit Descriptor Formatter Edit Descriptors an unsigned integer constant that defines the number base of the external data and cannot be less than 2 or greater than 16. b On output, the Iw edit descriptor causes the external field to consist of zero or more leading blanks (followed by a minus if the value of the internal data is negative, or an optional plus otherwise), followed by the magnitude of the internal value in the form of an unsigned integer constant without leading zeros.
The L Edit Descriptor Formatter Edit Descriptors The “|” character is used to denote the boundaries of the output field. 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.
Formatter Edit Descriptors The M Edit Descriptor The M Edit Descriptor The mask formatting edit descriptor edits either alphanumeric or numeric data according to an editing pattern or mask. Special characters within the mask indicate where digits in the data are to be displayed; other characters are duplicated in the output field as they appear in the mask.
The M Edit Descriptor Formatter Edit Descriptors For example, a value that is intended to represent a date can be formatted with an M field descriptor as follows: Format Data Value Result M"99/99/99" 103179 |10/31/79| The following is a comparison of the effects of using the 9 and Z as digit selectors. The minus sign in the preceding examples is the symbol that is automatically displayed for negative values in the absence of any specification to the contrary by a decoration.
The O Edit Descriptor Formatter Edit Descriptors 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 Formatter Edit Descriptors 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 the following 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. After the field is processed, the current position is advanced by w characters.
Modifiers Formatter Edit Descriptors Modifiers Modifiers alter the normal effect of edit descriptors. Modifiers immediately precede the edit descriptor to which they apply. If modifiers immediately precede the left parenthesis of a group, the modifiers apply to each repeatable edit descriptor within the group. They are enclosed in brackets, and if more than one is present, they are separated by commas. Note. Modifiers are effective only on output. If they are supplied for input, they have no effect.
Overflow-Character Modifier (OC) Formatter Edit Descriptors Overflow-Character Modifier (OC) The overflow condition occurs if there are more characters to be placed into a field than there are positions provided by the edit descriptors. In the absence of any modifier or decoration to the contrary, if an overflow condition occurs in a numeric field, the field is filled with asterisks (*). This applies to the D, E, F, G, I, and M edit descriptors.
Symbol-Substitution Modifier (SS) Formatter Edit Descriptors The following formatting symbols can be altered by the SS modifier: Symbo l Function 9 Digit selector (M format) Z Digit selector, zero suppression (M format) V Decimal alignment character (M format) .
Decorations Formatter Edit Descriptors Decorations A decoration specifies a character string that can be added to the result field, the conditions under which the string is to be added, the location at which the string is to be added, and whether it is to be added before normal formatting is done or after it is completed. You can use multiple decorations, separated by commas, with the same edit descriptor.
Locations Formatter Edit Descriptors specifies that the string is to be inserted in the field if the data value is equal to or greater than zero. Locations The location specifier indicates where the string is to be added to the field. The A specifier states that the string is to begin in absolute position n within the field. The leftmost position of the field is position 1.
Processing Formatter Edit Descriptors Note. The following 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'*** ... *' (The number of asterisks is equal to the number of characteristics in the field width.
List-Directed Formatting Formatter Edit Descriptors List-Directed Formatting List-directed formatting provides the data conversion capabilities of the formatter without requiring the specification of a format. The FORMATDATA procedure determines the details of the data conversion, based on the types of the data elements.
Formatter Edit Descriptors List-Directed Output On input, a value separator is one of the following: • • • A comma or slash optionally preceded or optionally followed by one or more contiguous blanks (except within a character constant). One or more contiguous blanks between two constants or following the last constant (except embedded blanks surrounding the real or imaginary part of a complex constant). The end of the buffer (except within a character constant).
G Superseded Guardian Procedure Calls and Their Replacements This appendix contains the following tables listing superseded Guardian procedures and their replacements: • • • • • Table G-1, Superseded Guardian Procedures and Their Replacements (H06.
Superseded Guardian Procedure Calls and Their Replacements Table G-3.
Superseded Guardian Procedure Calls and Their Replacements Table G-5 lists the C-series Guardian procedures that are superseded beginning in the D-series RVU of the operating system and indicates the new procedures that replace them. The superseded procedures continue to be supported for compatibility. Table G-5.
Superseded Guardian Procedure Calls and Their Replacements Table G-5.
Superseded Guardian Procedure Calls and Their Replacements Table G-5.
H Documented Guardian Procedures The following list shows all documented Guardian procedures and the manuals in which they are described: ABEND Guardian Procedure Calls Reference Manual ABORTTRANSACTION TMF Application Programmer’s Guide ACTIVATEPROCESS Guardian Procedure Calls Reference Manual ACTIVATERECEIVETRANSID TMF Application Programmer’s Guide ADDDSTTRANSITION Guardian Procedure Calls Reference Manual ADDRESS_DELIMIT_ Guardian Procedure Calls Reference Manual ADDRTOPROCNAME Guardian Pro
Documented Guardian Procedures CANCELTIMEOUT Guardian Procedure Calls Reference Manual CHANGELIST Guardian Procedure Calls Reference Manual CHECK^BREAK Guardian Procedure Calls Reference Manual CHECK^FILE Guardian Procedure Calls Reference Manual CHECKALLOCATESEGMENT Guardian Procedure Calls Reference Manual CHECKCLOSE Guardian Procedure Calls Reference Manual CHECKDEALLOCATESEGMENT Guardian Procedure Calls Reference Manual CHECKDEFINE Guardian Procedure Calls Reference Manual CHECKMONITOR
Documented Guardian Procedures CONFIG_GETINFO_BYNAME_ Guardian Procedure Calls Reference Manual CONFIG_GETINFO_BYNAME2_ Guardian Procedure Calls Reference Manual CONTIME Guardian Procedure Calls Reference Manual CONTROL Guardian Procedure Calls Reference Manual CONTROLBUF Guardian Procedure Calls Reference Manual CONTROLMESSAGESYSTEM Guardian Procedure Calls Reference Manual CONVERTASCIIEBCDIC Guardian Procedure Calls Reference Manual CONVERTPROCESSNAME Guardian Procedure Calls Reference Man
Documented Guardian Procedures DEFINEMODE Guardian Procedure Calls Reference Manual DEFINENEXTNAME Guardian Procedure Calls Reference Manual DEFINEPOOL Guardian Procedure Calls Reference Manual DEFINEREADATTR Guardian Procedure Calls Reference Manual DEFINERESTORE Guardian Procedure Calls Reference Manual DEFINERESTOREWORK Guardian Procedure Calls Reference Manual DEFINERESTOREWORK2 Guardian Procedure Calls Reference Manual DEFINESAVE Guardian Procedure Calls Reference Manual DEFINESAVEWORK
Documented Guardian Procedures EMSADDSUBJECTMAP EMS Manual EMSADDTOKENMAPS EMS Manual EMSADDTOKENS EMS Manual EMSGET EMS Manual EMSGETTKN EMS Manual EMSINIT EMS Manual EMSINITMAP EMS Manual EMSTEXT EMS Manual ENDTRANSACTION TMF Application Programmer’s Guide ENFORMFINISH Enform User’s Guide ENFORMRECEIVE Enform User’s Guide ENFORMSTART Enform User’s Guide ERRNO_GET Guardian Procedure Calls Reference Manual EXTENDEDIT Guardian Procedure Calls Reference Manual FILE_ALTERLIST_ Gua
Documented Guardian Procedures FILEERROR Guardian Procedure Calls Reference Manual FILEINFO Guardian Procedure Calls Reference Manual FILEINQUIRE Guardian Procedure Calls Reference Manual FILENAME_COMPARE_ Guardian Procedure Calls Reference Manual FILENAME_DECOMPOSE_ Guardian Procedure Calls Reference Manual FILENAME_EDIT_ Guardian Procedure Calls Reference Manual FILENAME_FINDFINISH_ Guardian Procedure Calls Reference Manual FILENAME_FINDNEXT_ Guardian Procedure Calls Reference Manual FILE
Documented Guardian Procedures GETCPCBINFO Guardian Procedure Calls Reference Manual GETCRTPID Guardian Procedure Calls Reference Manual GETDEVNAME Guardian Procedure Calls Reference Manual GETINCREMENTEDIT Guardian Procedure Calls Reference Manual GETPOOL Guardian Procedure Calls Reference Manual GETPOOL_PAGE_ Guardian Procedure Calls Reference Manual GETPOSITIONEDIT Guardian Procedure Calls Reference Manual GETPPDENTRY Guardian Procedure Calls Reference Manual GETREMOTECRTPID Guardian Pr
Documented Guardian Procedures INTERPRETTIMESTAMP Guardian Procedure Calls Reference Manual INTERPRETTRANSID TMF Application Programmer’s Guide JULIANTIMESTAMP Guardian Procedure Calls Reference Manual KEYPOSITION Guardian Procedure Calls Reference Manual KEYPOSITIONX Guardian Procedure Calls Reference Manual LABELEDTAPESUPPORT Guardian Procedure Calls Reference Manual LASTADDR Guardian Procedure Calls Reference Manual LASTADDRX Guardian Procedure Calls Reference Manual LASTRECEIVE Guardia
Documented Guardian Procedures MBCS_TRIMFRAGMENT_ Guardian Procedure Calls Reference Manual MEASCLOSE Measure Reference Manual MEASCONFIGURE Measure Reference Manual MEASCONTROL Measure Reference Manual MEASCOUNTERBUMP Measure Reference Manual MEASCOUNTERBUMPINIT Measure Reference Manual MEASGETVERSION Measure Reference Manual MEASINFO Measure Reference Manual MEASMONCONTROL Measure Reference Manual MEASMONSTATUS Measure Reference Manual MEASOPEN Measure Reference Manual MEASREAD Mea
Documented Guardian Procedures MYTERM Guardian Procedure Calls Reference Manual NEWPROCESS Guardian Procedure Calls Reference Manual NEWPROCESSNOWAIT Guardian Procedure Calls Reference Manual NEXTFILENAME Guardian Procedure Calls Reference Manual NO^ERROR Guardian Procedure Calls Reference Manual NODE_GETCOLDLOADINFO_ Guardian Procedure Calls Reference Manual NODENAME_TO_NODENUMBER_ Guardian Procedure Calls Reference Manual NODENUMBER_TO_NODENAME_ Guardian Procedure Calls Reference Manual NUMBE
Documented Guardian Procedures POSITION Guardian Procedure Calls Reference Manual POSITIONEDIT Guardian Procedure Calls Reference Manual PRINTCOMPLETE Spooler Programmer’s Guide PRINTCOMPLETE2 Spooler Programmer’s Guide PRINTINFO Spooler Programmer’s Guide PRINTINIT Spooler Programmer’s Guide PRINTINIT2 Spooler Programmer’s Guide PRINTREAD Spooler Programmer’s Guide PRINTREADCOMMAND Spooler Programmer’s Guide PRINTSTART Spooler Programmer’s Guide PRINTSTART2 Spooler Programmer’s Guide
Documented Guardian Procedures PROCESSHANDLE_DECOMPOSE_ Guardian Procedure Calls Reference Manual PROCESSHANDLE_GETMINE_ Guardian Procedure Calls Reference Manual PROCESSHANDLE_NULLIT_ Guardian Procedure Calls Reference Manual PROCESSHANDLE_TO_CRTPID_ Guardian Procedure Calls Reference Manual PROCESSHANDLE_TO_FILENAME_Guardian Procedure Calls Reference Manual PROCESSHANDLE_TO_STRING_ Guardian Procedure Calls Reference Manual PROCESSINFO Guardian Procedure Calls Reference Manual PROCESSNAME_CREATE
Documented Guardian Procedures REFPARAM_BOUNDSCHECK_ Guardian Procedure Calls Reference Manual REFRESH Guardian Procedure Calls Reference Manual REMOTEPROCESSORSTATUS Guardian Procedure Calls Reference Manual REMOTETOSVERSION Guardian Procedure Calls Reference Manual RENAME Guardian Procedure Calls Reference Manual REPLY Guardian Procedure Calls Reference Manual REPLYX Guardian Procedure Calls Reference Manual REPOSITION Guardian Procedure Calls Reference Manual RESERVELCBS Guardian Proced
Documented Guardian Procedures SERVERCLASS_SEND_ TS/MP Pathsend and Server Programming Manual SERVERCLASS_SEND_INFO_ TS/MP Pathsend and Server Programming Manual SET^FILE Guardian Procedure Calls Reference Manual SETJMP_ Guardian Procedure Calls Reference Manual SETMODE Guardian Procedure Calls Reference Manual SETMODENOWAIT Guardian Procedure Calls Reference Manual SETMYTERM Guardian Procedure Calls Reference Manual SETPARAM Guardian Procedure Calls Reference Manual SETSTOP Guardian Proce
Documented Guardian Procedures SIGSUSPEND_ Guardian Procedure Calls Reference Manual SORTBUILDPARM FastSort Manual SORTERROR FastSort Manual SORTERRORDETAIL FastSort Manual SORTERRORSUM FastSort Manual SORTMERGEFINISH FastSort Manual SORTMERGERECEIVE FastSort Manual SORTMERGESEND FastSort Manual SORTMERGESTART FastSort Manual SORTMERGESTATISTICS FastSort Manual SPI_BUFFER_FORMATFINISH_ DSM Template Services Manual SPI_BUFFER_FORMATNEXT_ DSM Template Services Manual SPI_BUFFER_FORMAT
Documented Guardian Procedures SQLCADISPLAY SQL/MP Programming Manual for C, SQL Programming Manual for TAL SQLCAFSCODE SQL/MP Programming Manual for COBOL85, SQL/MP Programming Manual for C, SQL Programming Manual for TAL SQLCAGETINFOLIST SQL/MP Programming Manual for C, SQL Programming Manual for TAL SQLCATOBUFFER SQL/MP Programming Manual for C, SQL Programming Manual for TAL SQLGETCATALOGVERSION SQL/MP Programming Manual for COBOL85, SQL/MP Programming Manual for C, SQL Programming Manual for
Documented Guardian Procedures SYSTEMENTRYPOINT_RISC_ Guardian Procedure Calls Reference Manual SYSTEMENTRYPOINTLABEL Guardian Procedure Calls Reference Manual TAKE^BREAK Guardian Procedure Calls Reference Manual TEXTTOSSID Guardian Procedure Calls Reference Manual TEXTTOTRANSID TMF Application Programmer’s Guide TMF_SETTXHANDLE_ TMF Application Programmer’s Guide TMF_SUSPEND_ TMF Application Programmer’s Guide TMF_TXBEGIN_ TMF Application Programmer’s Guide TMF_BEGINTAG_FROM_TXHANDLE_TMF A
Documented Guardian Procedures USERIDTOUSERNAME Guardian Procedure Calls Reference Manual USERNAMETOUSERID Guardian Procedure Calls Reference Manual USESEGMENT Guardian Procedure Calls Reference Manual VERIFYUSER Guardian Procedure Calls Reference Manual VRO_SET_ Guardian Procedure Calls Reference Manual WAIT^FILE Guardian Procedure Calls Reference Manual WRITE Guardian Procedure Calls Reference Manual WRITE^FILE Guardian Procedure Calls Reference Manual WRITEEDIT Guardian Procedure Calls
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.
Using the DIVER and DELAY Programs • Running the DIVER Program Bit 0 of the processor’s switch register is set to 1; this condition is necessary for reloading the processor. If either condition fails, DIVER abends and the processor continues to be operational. The syntax to run DIVER is: DIVER / run-option [ , run-option ] ... / DIVER is an implicit RUN command that starts a DIVER process. run-option is any valid option for the TACL RUN command.
Using the DIVER and DELAY Programs Running the DELAY Program 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.
Using the DIVER and DELAY Programs Example Using DIVER and DELAY Example Using DIVER and DELAY The following example uses the DIVER and DELAY programs to cause both processors (0 and 1) of a two-processor system to fail and reload repeatedly, approximately once every four minutes. You can increase this cycle time if your application requires more time to recover. Note.
J System Limits This appendix presents a series of tables that summarize the architectural and programmatic limits that apply on NonStop servers. For SQL/MP limits, refer to the “Limits” entry in the SQL/MP Reference Manual. For TMF limits, refer to the TMF Configuration and Planning Guide. For the locations of other published limits, refer to Table J-7 on page J-9 Table J-1.
System Limits Table J-1. System-Level Limits (page 2 of 2) Maximum Value Limit Description Number of tape drives per node in a labeled tape environment 20 System-generated names (default, 4-character form) 30,720 System-generated names (5-character form) 30,000 Explicitly reserved process names -- Comment Names in the form $Xnaa, $Ynaa, $Znaa, where a is alphanumeric and n is numeric Names in the form $Xnnnn, $Ynnnn, $Znnnn $X..., $Y..., $Z...
System Limits Table J-2. Per-Process Limits (page 2 of 2) Limit Description Maximum Value 1.5 GB Open user semaphores Comment H06.01 and all subsequent H-series releases 64 Concurrent outstanding messages Time Slice 4,096 512 default (Maximums for incoming and outgoing messages are set separately, but have the same limits.) 2 seconds for G-series releases The time slice is the amount of time a process can run at a given priority before it is declared CPU-bound and has its priority decremented.
System Limits Table J-3. Per-Processor Limits (page 2 of 2) Timer tick value 10 millisecs for TNS/R and 1 microsecs for TNS/E Timestamp resolution 1 microsec Physical memory Varies with server model Aliased virtual memory < 1 GB For example, see parameter to DELAY procedure. 8,189 unit segments, where 1 unit segment = 128 KB (G04.00 and earlier G-series releases) 7,933 unit segments, where 1 unit segment = 128 KB (G05.
System Limits Table J-4. TNS vs. Native limits (page 2 of 3) TNS user code and user library 32 segments TNS total stack and globals 64 KB TNS total user data space 128 KB Accelerated user code, user library, or system code 28 MB each Native user code 32 MB on TNS and TNS/R systems, 256 MB on TNS/E systems Native user library 32 MB on TNS and TNS/R systems, 256 MB on TNS/E systems Does not include extended segments data space.
System Limits Table J-4. TNS vs. Native limits (page 3 of 3) Native globals + heap + flat segments + stack 640 MB Prior to G05 1.1 GB G05 releases 1.5 GB H-series releases Table J-5. Enscribe File System Limits (page 1 of 2) 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.
System Limits Table J-5.
System Limits Table J-6. DP2 Limits Limit Description Maximum Value Volumes per physical disk 1 Structured disk block size 4 KB Unstructured disk file buffer size 4 KB Number of extents per file <= 978 Disk volume size 1 TB Cache per volume 1 GB Bulk I/O transfer 56 KB bytes Number of locks 5,000 per file open and per transaction Comment Can be mirrored. Depends on number of partitions and alternate keys specified.
System Limits Table J-7.
K Character Set Translation Table K-1 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 K-1 is consistent with that in other HP products. Table K-1.
Index A A edit descriptor F-9 A specifier F-27 ABEND procedure 2-2 and NetBatch 2-7 compared with STOP 2-5 Abnormal deletion of a process 2-2, 12-196 Aborting a process 2-2, 12-196 Access control block 5-106, 8-6 Access ID 12-66 of the calling process 12-207 of the calling process's creator 3-176 security level 5-123, 11-23 Access mode checking, on open 5-123, 11-23 Access path, in key-sequenced, entrysequenced, and relative files 5-142, 7-55 ACTIVATEPROCESS procedure 2-9 ADDDSTTRANSITION procedure 2-11 Add
C Index Backup process in monitoring state 3-30, 3-39, 3-69, 5-17, 5-130 recovering from primary failure 3-42 unable to communicate with 3-41 Base address equivalencing 2-38 Batch processing and NEWPROCESS procedure 10-22 and PROCESS_CREATE_ procedure 12-51 and PROCESS_SPAWN_ procedure 12-194 Binary edit descriptor F-11 Binary semaphore procedures BINSEM_CLOSE_ 2-55 BINSEM_CREATE_ 2-57 BINSEM_FORCELOCK_ 2-61 BINSEM_LOCK_ 2-64 BINSEM_OPEN_ 2-67 BINSEM_UNLOCK_ 2-70 using 2-58 Binary semaphores closing 2-55
C Index Calendars timestamp range checking 7-50 returned 7-51 using to change system clock 14-119 CANCEL procedure 3-3 Canceling a process-time timer 3-5 an elapsed-time timer 3-9 nowait operations a specific operation 3-7 the oldest incomplete operation 3-3 CANCELPROCESSTIMEOUT procedure 3-5 CANCELREQ procedure 3-7 CANCELTIMEOUT procedure 3-9 CEXTDECS support in H-Series systems 1-12 CHANGELIST procedure 3-11 Changing disk file names 5-135, 13-55 priority 12-33, 12-38, 12-153 the home terminal 14-108 Cha
C Index CLASS SPOOL DEFINEs E-5 CLASS SUBSORT DEFINEs E-4 CLASS TAPE DEFINEs E-5 CLASS TAPECATALOG DEFINEs E-5 Classes of DEFINEs E-1 Clearing poll state bit 3-13 Clock, changing system 14-119 CLOSE procedure 3-75 CLOSEALLEDIT procedure 3-81 CLOSEEDIT procedure 3-82 CLOSEEDIT_ procedure 3-84 CLOSE^FILE procedure 3-78 Closing a nowait file 3-76, 5-15 an open file 3-75, 3-78, 5-14 files in a backup process 3-30, 5-17 files using SIO procedure 3-78 IOEdit files 3-81, 3-82, 3-84 Colon edit descriptor F-8 Comm
C Index OSS pathnames to Guardian file names 12-5 process handle to file name 12-221 to process file name 12-221 to process ID 12-219 to process string 12-223 process ID to process handle 3-177 process name, from local to network form 3-144, 5-193 quad microsecond process time 3-145 system messages to D-format 11-11 system name to system number 10-40 system number to system name 10-42 Unique Timestamp into a Julian Timestamp 15-18 CONVERTPROCESSNAME procedure 3-144 CONVERTPROCESSTIME procedure 3-145 CONVE
D Index D D edit descriptor F-11 Data communication procedures CHANGELIST 3-11 DEFINELIST 4-21 HALTPOLL 7-2 SETPARAM 14-110 Data conversion 5-241, 5-245 Data segment allocating extended 2-21, 14-6 deallocating extended 4-4, 14-23 information on extended 14-29, 14-32 Date converting from Julian day number to year, day, month 7-47 converting Gregorian to Julian 3-90 obtaining in integer form 15-8 Date and time array, form of 7-49 Daylight saving time (DST) adding an entry to the DST table 2-11, 3-147 defini
D Index DEFINE procedures DEFINEREADATTR 4-32 DEFINERESTORE 4-36 DEFINERESTOREWORK[2] 4-39 DEFINESAVE 4-41 DEFINESAVEWORK[2] 4-44 DEFINESETATTR 4-45 DEFINESETLIKE 4-48 DEFINEVALIDATEWORK 4-50 DEFINEADD procedure 4-12 DEFINEDELETE procedure 4-15 DEFINEDELETEALL procedure 4-17 DEFINEINFO procedure 4-18 DEFINELIST procedure 4-21 DEFINEMODE procedure 4-24 DEFINENEXTNAME procedure 4-26 DEFINEPOOL procedure 4-28 DEFINEREADATTR procedure 4-32 DEFINERESTORE procedure 4-36 DEFINERESTOREWORK[2] procedures 4-39 DEFI
D Index Device-dependent I/O operations requiring a data buffer, using the CONTROLBUF procedure 3-136 using the CONTROL procedure 3-126 DEVICE_GETINFOBYLDEV_ procedure 4-56 DEVICE_GETINFOBYNAME_ procedure 4-68 Diagnostic bytes for X25AM 14-110 Dirty pages in memory copied to swap file 4-4, 14-24, 14-27 Disabling receipt of new system messages 9-65 Disk extents, allocating and deallocating 3-132 Disk file names C-series syntax D-8 D-series syntax D-2 expanded form of 5-237 Disk files See also File characte
E Index Disk files unlocking records of 15-23 unstructured buffer size 5-158 using pseudo-temporary names 3-170 verify writes on or off 5-158 when reading and record does not exist 13-30 writing EOF to an unstructured file 3-134 writing out EOF, free-list pointers, audit buffer, cache data buffer 4-79, 13-49 Disk process See DP2 DISKINFO procedure 4-81 DISK_REFRESH_ procedure 4-79 Distributed Name Service file name conversion 5-224, 5-228, 5-239 file name expansion 5-226 DIVER program I-1 DNUMIN procedure
E Index Edit descriptors Z F-22 / F-8 < F-8 Edit files, nowait access 7-39 Editing file names 5-174 EDITREAD control block 4-105 EDITREAD procedure 4-101 EDITREADINIT procedure 4-104 use with EDITREAD procedure 4-104 Elapsed time and a timeout message 14-149 End-of-file pointer 5-81, 5-154 and segment deallocation 4-5, 14-25, 14-28 Entry point names, associated with a procedure label 14-177, 14-179 ENV register bits for space ID 3-179 EOF See End-of-file pointer ERRNO_GET_ procedure 4-106 Error handling a
F Index Extents, allocating and deallocating 3-132 External declarations for Guardian procedure parameters 1-6 for Guardian procedures 1-5 External file names, syntax defined D-8 F F edit descriptor F-14 F specifier F-27 FCBs See File control blocks Field-blanking modifiers F-23 File access, sequential 5-117, 11-17 File characteristics, checking using CHECK^FILE 3-24 File characteristics, obtaining alternate key parameters 5-78, 5-218 block length 5-73, 5-218 current key length 5-70, 5-216 current key sp
F Index File names comparing 5-168, 5-232 converting external to internal form 5-235 internal to external form 5-230 to C-format file names 5-204 to Guardian file names 12-5 to OSS pathnames 5-206 to process handles 5-210 decomposing 5-170 editing 5-174 expanding 5-235 for nondisk devices D-3 fully and partially qualified D-1, D-8 obtaining, in alphabetic order 10-32 reserved D-1 unresolving 5-212 File opening 5-112, 11-14 File position by primary key 12-27 saving 5-140, 14-3 File purging 5-132, 12-269 Fi
F Index Filenum parameter in FILERECINFO procedure 5-216 FILE_CLOSE_ procedure 5-14 FILE_CLOSE_CHKPT_ procedure 5-17 FILE_GETINFOLIST_ procedure 5-67 FILE_GETINFO_ procedure 5-58 FILE_OPEN_ procedure 5-114 FILE_OPEN_CHKPT_ 5-130 FILE_RESTOREPOSITION_ procedure 5-138 GETINCREMENTEDIT procedure 6-11 GETPOSITIONEDIT procedure 6-17 GETSYNCINFO procedure 6-26 HALTPOLL procedure 7-2 INCREMENTEDIT procedure 7-35 LOCKFILE procedure 8-12 LOCKREC procedure 8-21 NUMBEREDIT procedure 10-54 OPEN procedure 11-15 OPENED
F Index File-system procedures FILE_GETINFO_ 5-57 FILE_GETLOCKINFO_ 5-96 FILE_GETOPENINFO_ 5-102 FILE_GETRECEIVEINFO_ 5-106 FILE_OPEN_ 5-112 FILE_PURGE_ 5-132 FILE_RENAME_ 5-135 FILE_RESTOREPOSITION_ 5-138 FILE_SAVEPOSITION_ 5-140 FILE_SETKEY_ 5-142 FILE_SETPOSITION_ 5-145 FNAME32COLLAPSE 5-224 FNAME32EXPAND 5-226 FNAME32TOFNAME 5-228 FNAMECOLLAPSE 5-230 FNAMECOMPARE 5-232 FNAMEEXPAND 5-235 FNAMETOFNAME32 5-239 GETDEVNAME 6-7 GETSYSTEMNAME 6-28 GROUPIDTOGROUPNAME 6-40 GROUPMEMBER_GETNEXT_ 6-42 GROUPNAMETO
G Index FILE_OPEN_ procedure options, parameters 5-116 FILE_OPEN_CHKPT_ procedure 5-130 FILE_PURGE_ procedure 5-132 FILE_RENAME_ procedure 5-135 FILE_RESTOREPOSITION_ procedure 5-138 FILE_SAVEPOSITION_ procedure 5-140 FILE_SETKEY_ procedure 5-142 FILE_SETPOSITION_ procedure 5-145 FILE_SETSYNCINFO_ procedure 5-147 Fill-character modifier F-23 Fixed-format edit descriptor F-14 FIXSTRING procedure 5-220 FL modifier F-23 Flags, parameters for OPEN procedure 11-15 Floating-point edit descriptor F-11, F-12 FNAM
H Index GIVE^BREAK procedure 6-32 GMOM process, notified of a deletion 12-199, 12-202 Greenwich mean time 7-47 Gregorian date and time array form 3-92 converting to 64-bit Julian 3-92 to Julian 3-90 definition of 3-90 GROUPIDTOGROUPNAME procedure 6-40 GROUPMEMBER_GETNEXT_ procedure 6-42 GROUPNAMETOGROUPID procedure 6-45 GROUP_GETINFO_ procedure 6-34 GROUP_GETNEXT_ procedure 6-37 H H edit descriptor F-5 HALTPOLL procedure 7-2 HEADROOM_ENSURE_ procedure 7-3 HEAPSORT procedure 7-6 HEAPSORTX_ procedure 7-8 H
J Index Inspect 4-7, 12-57 Integer edit descriptor F-16 Interchanging primary and backup after processor module reload 3-69 Internal file name D-10 converting to file name 11-9 Internal form, CPU interval clock 15-12 INTERPRETINTERVAL procedure 7-45 INTERPRETJULIANDAYNO procedure 7-47 INTERPRETTIMESTAMP procedure 7-49 Interprocess communication in FILE_OPEN_ procedure 5-126 in OPEN procedure 11-26 in READUPDATE[X] procedure 13-31 in REPLY[X] procedure 13-60 using WRITEREAD[X] procedure 16-21 Interval-cloc
L Index Key description, specifying in CREATE procedure 5-47 Key length, current 5-70, 5-216 Key positioning by alternate key 5-142, 7-55 by primary key 5-142, 7-55 Key specifier 5-143, 7-56 Key value, current 5-70, 5-216 KEYPOSITION[X] procedures 7-55 and file-system error 21 7-62 Key, current specifier 5-70, 5-216 Key-sequenced parameters array format 3-161 obtaining 5-73, 5-218 specifying in CREATE procedure 3-159 specifying in FILE_CREATELIST_ procedure 5-43 specifying in FILE_CREATE_ procedure 5-37
M Index Logical device number obtaining, using FILE_GETINFOLIST_ procedure 5-72 Logical edit descriptor F-18 Logical record length 5-72, 5-218 LONGJMP 8-24 LOOKUPPROCESSNAME procedure 8-27 LST See Local standard time M M edit descriptor F-19 Magnetic tape control action when closing 3-75 Magnetic tape, control action when closing 5-15 Managing memory pools 4-30, 12-14 Mask edit descriptor F-19 Maximum extents upper limit 3-166, 5-38 Maximum extents, upper limit 5-38 Maximum number of open files 5-118, 11
N Index Memory pages for a process opened nowait 10-26 Memory pools, managing 4-30, 12-14 Memory usage information, obtaining 12-242 Memory, block of obtaining from a buffer pool 6-13, 12-19 returning to a buffer pool 12-23, 12-272 Memory-management procedures ALLOCATESEGMENT 2-21 CURRENTSPACE 3-179 DEALLOCATESEGMENT 4-4 DEFINEPOOL 4-28 GETPOOL 6-13 POOL_CHECK_ 12-9 POOL_DEFINE_ 12-12 POOL_GETINFO_ 12-16 POOL_GETSPACE_ 12-19 POOL_PUTSPACE_ 12-23 POOL_RESIZE_ 12-25 PUTPOOL 12-272 RESIZEPOOL 13-67 USESEGMEN
O Index New processes execution priority 10-2, 12-38, 12-116, 12-166 memory pages 10-4, 12-44, 12-183 processor location 10-5, 12-42 NEWPROCESS procedure 10-2 and batch processing 10-22 device subtype for named processes 10-20 startup messages 10-20 NEWPROCESSNOWAIT procedure 10-24 startup messages 10-30 NEXTFILENAME procedure 10-32 Next-record pointer 5-70, 5-154 Node name converting to node number 10-40 Node number converting to node name 10-42 NODENAME_TO_NODENUMBER_ procedure 10-40 NODENUMBER_TO_NODEN
P Index OPENINFO procedure 11-51 Opening a file 5-112, 11-14 for a backup process 3-39, 5-130 same parameters for CHECKOPEN as OPEN 3-39 Opens, limit on number of 5-119, 11-20 OPEN^FILE procedure 11-29 Operational state, of a processor 12-258 Operations for CHECK^FILE procedure 3-24 for CONTROL procedure 3-128 Operations for SET^FILE procedure 14-60 OSS process arguments 12-96 command 12-96 ctty 12-88 group leader 12-98 obtaining information about 12-60, 12-69 parent pid 12-97 pid 12-68 program pathname 1
P Index Pools size of memory obtained from a buffer 6-13, 12-19 using a portion of a user’s stack as 4-29, 12-13 POOL_CHECK_ procedure 12-9 POOL_DEFINE_ procedure 12-12 POOL_GETINFO_ procedure 12-16 POOL_GETSPACE_ procedure 12-19 POOL_GETSPACE_PAGE_ procedure 12-20 POOL_PUTSPACE_ procedure 12-23 POOL_RESIZE_ procedure 12-25 POSITION procedure 12-27 POSITIONEDIT procedure 12-31 Positioning by primary key, in key-sequenced files 5-142, 7-55 by primary key, in relative and entry sequenced files 5-145, 12-27
P Index Process checkpointing block of data area 3-43 creation, in nowait manner 10-24 deletion 12-196, 14-166 notification of 14-162, 14-164 protecting against 14-115 getting information about its own PCB 6-2 monitoring 3-71, 11-47 obtaining information about 12-60, 12-69, 12-108 owns BREAK 3-14 pair activation 2-9, 12-35 deletion 12-196, 14-166 obtaining descriptions by index 8-27 suspension 12-204, 14-175 unnamed 3-40, 5-18, 5-131 when both members are activated 2-9, 12-35 when both members are suspend
P Index Process control procedures SIGNALTIMEOUT 14-149 STEPMOM 14-162 STOP 14-166 SUSPENDPROCESS 14-175 Process creation in nowait manner 10-24 Process creation, errors indicating outcome 10-5, 10-27, 12-40, 12-117 Process data stack checkpointing 3-43, 3-49 Process descriptors D-6 Process file name C-series syntax D-11 D-series syntax for named processes D-5 for unnamed processes D-4 Process handle comparing 12-211 converting to file name 12-221 to process file name 12-221 to process ID 12-219 to proces
P Index Process names creating 3-169, 12-234 in NEWPROCESS procedure 10-5 in NEWPROCESSNOWAIT procedure 10-27 in PROCESS_CREATE_ procedure 12-43 in PROCESS_SPAWN_ procedure 12-183 reserved B-1 unique network-wide 3-173 Process open message 5-128, 11-27 Process pair activation 2-9, 12-35 changing execution priority 2-32, 12-153 deletion 14-166 obtaining descriptions by index 8-27 obtaining information about 12-108 suspension 12-204, 14-175 unnamed 3-40, 5-18, 5-131 when both members are activated 2-9, 12-3
Q Index PROCESS_GETINFOLIST_ procedure 12-69 PROCESS_GETINFO_ procedure 12-60 PROCESS_GETPAIRINFO_ procedure 12-108 PROCESS_LAUNCH_ procedure 12-116 PROCESS_SETINFO_ procedure 12-153 PROCESS_SETSTRINGINFO_ procedure 12-162 PROCESS_SPAWN_ procedure 12-166 and batch processing 12-194 PROCESS_STOP_ procedure 12-196 PROCESS_STOP_ procedure and NetBatch 12-202 PROCESS_SUSPEND_ procedure 12-204 Process’s data area, checkpointing a block of the 3-43 Program file and user library file differences 10-19, 12-48, 12
S Index REFRESH procedure 13-49 Register returning the stack-marker ENV 3-179 Registers, ‘L’ and ‘S’ 2-35 Relative byte address locking 8-23 Reload of a CPU, elapsed time since 3-153 Reloading a processor module 3-70 Remote CPU failures 13-51 status changes 9-63 Remote data terminal equipment address 14-110 Remote DCT entries entering 3-174 Remote DCT entries, obtaining 8-28 Remote process CRTPID 6-22 Remote process names, creating 3-172 REMOTEPROCESSORSTATUS procedure 13-51 REMOTETOSVERSION procedure 13-
S Index Segment ID ranges 2-22, 14-8 information on extended data 12-248, 14-29, 14-32 Segment ID in AWAITIO[X] procedure 2-46 SEGMENTSIZE procedure 14-39 SEGMENT_ALLOCATE_ procedure 14-6 SEGMENT_ALLOCATE_CHKPT_ procedure 14-18 SEGMENT_DEALLOCATE_ procedure 14-23 SEGMENT_DEALLOCATE_CHKPT_ procedure 14-26 SEGMENT_GETBACKUPINFO_ procedure 14-29 SEGMENT_GETINFO_ procedure 14-32 SEGMENT_USE_ procedure 14-36 SENDBREAKMESSAGE procedure 14-41 Separate opens by same requester 5-109, 13-43 Sequential block bufferi
S Index SIGNALTIMEOUT procedure 14-149 Signed integer values, converting to 10-56 SIGSAVE_DEF_ define 14-135 SIGSETJMP 14-155 SIGSETJMP_ procedure 14-155 SIO procedures See Sequential I/O procedures Slash edit descriptor F-8 Sort functions, arrays of equal-sized elements 7-6, 7-8 SP edit descriptor F-7 Space ID and the stack marker ENV register 2-38 bits in the ENV register 3-179 caller, returned 3-179 definition 2-38 Specifier of key in error 5-70, 5-217 Specifiers F-26 A F-27 conditions F-26 F F-27 loca
T Index Swap file when using SEGMENT_ALLOCATE_ 14-10, 14-19 Switching primary and backup processes 3-69 Symbolic debugger 4-7, 12-57 Symbol-substitution modifier F-24 Sync ID definition 5-108, 13-42 obtaining from FILE_GETRECEIVEINFO_ procedure 5-107 obtaining from RECEIVEINFO procedure 13-39 Synchronization block for a disk file 6-26 of a process pair, obtaining 14-117 Sync-depth in FILE_OPEN_ procedure 5-115 in OPEN procedure 11-15 Syntax of Guardian procedure calls, general example 1-7 Synthetic proces
T Index Text buffer, for EDITREAD procedure preparing 4-105 using 4-101 Text lines transferred 4-102 TEXTTOSSID procedure 15-4 The 4-90, 4-92, 4-97, 4-99, 5-138, 5-140, 5-145, 5-147, 14-139 Time execution of a calling process returned 9-73 of any process in the network 12-266 obtaining in integer form 15-8 Time and day array form 7-49 Time limit in FILE_COMPLETE_ procedure 5-20 Time limit in AWAITIO[X] procedure 2-45 Time measured elapsed time that process executes 14-150 while the process is executing 14
U Index Traps bounds violation 12-23, 12-272 faulty parameters 6-14, 12-20 IEEE floating point 5-254 Tributary stations affect of poll bit 3-13 Tributary stations, specifying station addresses 4-22 TS_NANOSECS_ procedure 15-15 TS_UNIQUE_COMPARE_ procedure 15-16 TS_UNIQUE_CONVERT_TO_JULIAN_ procedure 15-18 TS_UNIQUE_CREATE_ procedure 15-19 U Unique network-wide process names See PROCESSNAME_CREATE and CREATEREMOTENAME procedures UNLOCKFILE procedure 15-20 Unlocking disk files 15-20 records 15-20, 16-34 UN
V Index Utility procedures HIST_INIT_ 7-29 INITIALIZER 7-40 INTERPRETINTERVAL 7-45 INTERPRETJULIANDAYNO 7-47 INTERPRETTIMESTAMP 7-49 JULIANTIMESTAMP 7-51 LASTADDR 8-3 LASTADDRX 8-4 MONITORNEW 9-65 MYPROCESSTIME 9-73 NUMIN 10-56 NUMOUT 10-58 PROCESSORTYPE 12-260 PROCESSOR_GETNAME_ 12-253 PROCESSTIME 12-266 PROCESS_DEBUG_ 12-54 REFPARAM_BOUNDSCHECK_ 13-44 REMOTETOSVERSION 13-53 RESIZESEGMENT 13-69 SETSYSTEMCLOCK 14-119 SHIFTSTRING 14-124 SYSTEMENTRYPOINTLABEL 14-179 SYSTEMENTRYPOINT_RISC_ 14-177 TEXTTOSSID
Special Characters Index $RECEIVE and CLOSE^FILE SIO procedure 3-79 file obtaining the message tag 5-106, 8-6, 13-39 obtaining the process ID 5-106, 8-6, 13-39 obtaining the sync ID 5-106, 13-39 reading messages 13-26 replying to a message 13-58 replying to queued messages 13-60 in FILE_OPEN_ procedure 5-126 in OPEN procedure 11-26 protocol, using INITIALIZER 7-43 $X process name 3-170, 3-173 $Y process name 3-170, 3-173 $Z process name 3-170, 3-173 &G'[0] relative address, obtaining 8-3 &L’ relative loca
