System Software Library Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide Abstract This manual describes the Distributed Systems Network Management (DSNM) services that support network management applications. It describes how to use the program frame and library services supplied by Tandem for the development of the subsystem interface processes that integrate additional subsystems into the base of DSNMmanaged subsystems.
Document History Edition Part Number Product Version Earliest Supported Release Published First 029783 DSMS C21 C20 December 1990 Second 109759 DSNM D30 D30.01 February 1996 New editions incorporate any updates since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).
New and Changed Information This edition of the Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide has been updated to include functions and features added to DSNM for the C31 and D30 releases of the product. The operating system for Tandem NonStop systems, formerly called the Guardian operating system, is now called the Tandem NonStop Kernel.
New and Changed Information iv 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Contents New and Changed Information iii About This Manual xv Notation Conventions xix 1.
3. I Process Development Process Contents The STATISTICS Command 2-17 The STATUS Command 2-19 The STOP Command 2-21 The UPDATE Command 2-23 3.
Contents 4.
5. DSNM Process Startup Functions Contents Command Requirements 4-11 The ABORT Command 4-12 The AGGREGATE Command 4-13 The INFO Command 4-15 The START Command 4-16 The STATISTICS Command 4-17 The STATUS Command 4-18 The STOP Command 4-20 5.
Contents A. DSNM Library Services The DSNMCom Prompt 7-3 Running DSNMCom Interactively 7-3 Running DSNMCom From an Input File 7-4 The Comment Character, COMMENT-CHAR 7-4 Using the Break Key 7-4 Setting Security Parameters in DSNMCom 7-5 The DSNMCom Commands 7-5 CLOSE Command 7-5 EXIT Command 7-5 FC Command 7-6 HELP Command 7-6 OPEN Command 7-7 QUIT Command 7-7 RESET Command 7-7 SET Command 7-7 SHOW Command 7-10 Executing DSNM Commands 7-11 DSNMCom Messages 7-12 DSNM Parser Errors 7-17 A.
A.
A.
B. DSNM Error Codes Contents _SIGNAL^EVENT A-113 _STARTUP A-114 _STARTUP^MODE A-116 _ST^INITIAL A-118 _ST^MIN^THREAD^STATE A-119 _SUBSYS^DEF A-120 _SUCCESSOR^LM A-122 _THREAD^CONTEXT^ADDRESS A-124 _THREAD^PROC A-125 _THREAD^STATE A-126 _THREAD^TERMINATION^CODE A-127 _THREAD^TERMINATION^PROC A-128 _TURNOFF A-129 _TURNON A-130 _UNGET^LM A-131 _UNPOP^LM A-132 _XADR^EQ A-133 _XADR^NEQ A-134 B.
C.
D. Sample I Process Program Code Contents D.
About This Manual The Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide is written for programmers who develop the interface processes (I processes) that allow subsystems or applications to be managed by network management products that Distributed Systems Network Management (DSNM) services support. DSNM services support network management applications that automate and simplify the management of Tandem systems and networks.
Where to Go for More Information • • • • About This Manual Appendix A, “DSNM Library Services,” describes the syntax and parameters (as applicable) for each procedure call, define, literal, global variable, and structure template. Appendix B, “DSNM Error Codes,” defines the ZDSN error codes.
About This Manual • Your Comments Invited NonStop TS/MP and Pathway System Management Guide, which provides guidelines for configuring and controlling Pathway transaction processing systems.
Your Comments Invited xviii About This Manual 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] Brackets.
General Syntax Notation Notation Conventions An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char..." Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.
Notation for Messages Notation Conventions !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 The following list summarizes the notation conventions for the presentation of displayed messages in this manual. Nonitalic text.
Notation for Management Programming Interfaces Notation Conventions % Percent Sign. A percent sign precedes a number that is not in decimal notation. The %þnotation precedes an octal number. The %Bþnotation precedes a binary number. The %Hþnotation precedes a hexadecimal number. For example: %005400 P=%p-register E=%e-register Notation for Management Programming Interfaces UPPERCASE LETTERS. Uppercase letters indicate names from definition files; enter these names exactly as shown.
1 Overview of DSNM Scope of This Section This section provides an overview of the Distributed Systems Network Management (DSNM) services, which collate information from multiple subsystems and provide a consistent view between network-management applications and the diverse subsystems being managed. What is DSNM? The DSNM product provides a management service layer between management applications and individual management facilities for Tandem subsystems and user applications.
Applications Supported by DSNM Overview of DSNM address day-to-day network-management issues. The DSMS products are primarily oriented toward early fault detection and recovery. NonStop NET/MASTER MS provides comprehensive collections of networkmanagement services, such as automated operations, capacity and change management, configuration management, problem management, and performance management. DSMS products are used by and with NonStop NET/MASTER MS.
Overview of DSNM NetCommand NonStop NET/MASTER MS NonStop NET/MASTER MS is a network-management product that allows you to monitor and manage a single Tandem system or an entire network from a single terminal. Having NonStop NET/MASTER MS installed on your system also allows your local system to be monitored and/or managed remotely as part of a network of systems managed by NonStop NET/MASTER MS, SOLVE management services, and NetView products.
NetStatus • • Overview of DSNM Display operational statistics about network objects (STATISTICS). Define how the DSNM services layer monitors subsystem objects (UPDATE). Use of NetCommand is discussed in the User’s Guide to DSNM Commands. NetStatus The NetStatus management application is a Pathway-environment application that uses the monitoring facility of DSNM to provide a full-screen status display, which is continuously updated.
Overview of DSNM • • • • The Operations Layer User ID Management Services (UMS), a security service that enables the definition of authorized NonStop NET/MASTER MS users and their associated functions and privileges. Inter-NET/MASTER Connection (INMC), which allows multiple NonStop NET/MASTER MS and SOLVE management services systems to be connected and controlled from one location.
The Operations Layer • • • • Overview of DSNM Format responses to DSNM commands for the NetCommand requester process. Send display set information to NetStatus. Execute non-DSNM commands for NetStatus. Log commands and responses. The Distributed Systems Management Solutions (DSMS) System Management Guide contains additional information on NetCommand components. NetStatus NetStatus is a full-screen interface to DSNM.
The Operations Layer Overview of DSNM Figure 1-2.
The Management Services Layer Overview of DSNM The Management Services Layer The management services layer performs services for the operations layer. It provides for object resolution, the routing of commands to appropriate nodes and subsystems, and the handling of event messages. Tandem's Distributed Systems Management (DSM) services contribute object resolution and event management facilities. Figure 1-2 displays the DSNM and DSM functional connections.
Overview of DSNM • The object monitor process (OMON), which performs the following • • • • • The Management Services Layer Receives state change information from the event monitoring processes (E processes, discussed later in this subsection). Creates and maintains an in-memory database of current object state information. Responds to command server requests for object state information. Receives update changes from the database interface process (discussed later in this subsection).
The Subsystem Layer • • Overview of DSNM The conversational interface processes (CIP), which provides access to conversational utilities. It creates and terminates utility processes and emulates a terminal from the utility’s point of view. An event monitoring process (E process) for each supported subsystem provides the interface between the targeted subsystem and the DSNM object monitoring services.
The Subsystem Layer Overview of DSNM Figure 1-3. The Subsystem Layer NetworkManagement Applications DSNM I Processes CI EMS E Processes Management Process Manager Process Subsystem Process Other Subsystem Processes OBJ OBJ OBJ OBJ OBJ OBJ OBJ OBJ 004 Subsystem Objects A subsystem object is an entity subject to independent reference or control by a subsystem CI process.
Installing DSMS Products • • • • Overview of DSNM PATHMON-controlled terminal control processes, terminals, and server classes Expand paths and lines Tandem NonStop Kernel disks and processors Spooler devices See the Tandem NonStop Kernel Documents (softdocs) for a complete list of the subsystems supported by the current level of your DSNM software. Installing DSMS Products DSMS software arrives at your site on a site update tape (SUT).
Installing More Than One Copy of DSNM Concurrently Overview of DSNM Figure 1-4. DSNM Process Startup and Configuration Components $SYSTEM.SYSTEM.DSNM DSNM Config File ... DSNM Config File User-Supplied DSNM Configuration Files $SYSTEM.SYSTEM.
Mixed Network Requirements Overview of DSNM To run concurrent copies with no DSNM configuration, use the standard names and change only the process prefix character. If you are running DSNM under NonStop NET/MASTER MS, no special configuration is required. DSNM processes take their process prefix character from the first character of the NonStop NET/MASTER NCP process (refer to the NonStop NET/MASTER MS System Management Guide for more information).
2 DSNM Commands Scope of This Section This section describes the DSNM commands that your subsystem interface process (I process) must support. It provides syntax descriptions in sufficient detail to allow you to test the commands in an end-user’s capacity, explains the effect of the valid modifiers on each command, and defines what the outcome of each command should be. For complete descriptions and syntax of all DSNM commands, see the User’s Guide to DSNM Commands.
Object Specification DSNM Commands Object Specification An object specification gives information that DSNM uses to identify objects against which a command is issued. If there is more than one object specification, each must be separated from the other by a comma. An object specification must include the name of at least one object.
Modifiers DSNM Commands [\node.]$manager] is a qualifier that identifies the name of the manager process for the objects you are specifying. (Specify it only if it is applicable to the specified subsystem.) Note. You must specify the node if it is not the local node and if any of the following are true: • • • • The name The name The name The name is a wild card(*). begins with a dollar sign ($). includes a manager. is not in the DNS database.
Modifiers • DSNM Commands State modifier—restricts the scope of the command to a subset of the specified objects on the basis of their states. The state modifier values are: DOWN Applies the command to only the objects that are DOWN. NOT-UP Applies the command to the objects that are DOWN or PENDING. NOTDOWN Applies the command to the objects that are UP or PENDING. UP Applies the command to only the objects that are UP.
Parameters DSNM Commands • Highlight modifier—limits the scope of the UPDATE and INQUIRE commands to a subset of the objects, based on the objects’ attributes in the DSNM object database. The highlight modifier values are: FROM-DISPLAY Causes the command to use the names on the NetStatus display instead of resolving them through Distributed Name Service (DNS), thus speeding name resolution. Refer to the User’s Guide to DSNM Commands for restrictions on using this parameter.
Considerations DSNM Commands Considerations The following considerations apply to all DSNM commands except the AGGREGATE command. For more information on object specification and modifiers, refer to the User’s Guide to DSNM Commands. • • • • You can use parentheses to nest object lists. Any modifiers that appear inside parentheses are limited to the object specifications within the parentheses, overriding any modifiers that apply to the entire command.
DSNM Commands Canceling Commands The command server initiates a cancellation by sending a cancel buffer (where _INPUT.MOD.Z^AMOD = ZDSN^AMOD^CANCEL) to the frame. The frame then redispatches the thread with an _EV^CANCEL event. The command thread is responsible for cleaning up its environment. Refer to the NetStatus User’s Guide to find out how to cancel commands issued from the command line in NetStatus. Note. You cannot cancel a command that is in progress in the NonStop NET/MASTER MS environment.
The ABORT Command DSNM Commands The ABORT Command The ABORT command causes DSNM to issue the subsystem-specific command(s) that stops each object. When an object is stopped, its state changes to the subsystem state that corresponds to the DSNM DOWN state. The ABORT command stops objects without waiting for any outstanding operations to be completed. This command is more emergency-oriented than the STOP command, which stops objects after completing outstanding operations.
DSNM Commands The ABORT Command Because subsystems generally must abort objects in a predetermined order, the ONLY hierarchy modifier is ineffective with certain object types if their subordinate objects are still up; that is, aborting certain object types forces their subordinates to be aborted also. The ABORT command is not appropriate for all object types; refer to the User’s Guide to DSNM Commands for details.
The AGGREGATE Command DSNM Commands The AGGREGATE Command Use the AGGREGATE command to obtain the status of each object under the specified manager process or subsystem. The response message comprises information that is collated into a summary of the number of objects of each type that are in the state UP, PENDING, DOWN, UNDEFINED, or IN ERROR. AGGREGATE [subsys] [\node]... [[UNDER [\node.]$manager]] [,[subsys] [\node]... [[UNDER [\node.]$manager]]]...
DSNM Commands The INFO Command The INFO Command Use the INFO command to obtain configuration information on objects. The INFO command is not appropriate for all object types. Refer to the User’s Guide to DSNM Commands for information on how the command is interpreted by each subsystem. INFO objectspec [, objectspec ]... [, hierarchy-modifier ] [, error-modifier ] objectspec is the object specification. The syntax for the object specification is provided in “Object Specification” on page 2-2.
The INFO Command DSNM Commands Printerfile: Tclprog: \BERLIN.$SYSLOG.TRSYS.
The INQUIRE Command DSNM Commands The INQUIRE Command Use the INQUIRE command to obtain the current status of objects as recorded in the DSNM object database. Response time to the INQUIRE command can be faster than that of the STATUS command, but the response to the STATUS command can be more up-to-date than that of the INQUIRE command. See “Considerations” for details. INQUIRE objectspec [, [, [, [, [, [, objectspec ]...
The INQUIRE Command DSNM Commands FROM-DISPLAY causes the command to use the names on the NetStatus display instead of resolving them through Distributed Name Service (DNS), thus speeding name resolution. The FROM-DISPLAY parameter is valid only if you are issuing a command from the NetStatus command line and all objects specified in the command appear on the NetStatus screen. (Refer to the NetStatus User’s Guide for more information on FROM-DISPLAY.
The START Command DSNM Commands The START Command The START command causes DSNM to issue the subsystem-specific command(s) that change each object to the subsystem state that corresponds to the DSNM UP state. If all objects specified in the command are started, there is no command response. If the command fails to start any of the objects, there is a response, listing the objects that were not started. If the command line contains a syntax error, you receive an error message.
The START Command DSNM Commands Example The following command starts the SNAX lines identified by the aliases BERLIN-ATMLINE and PARIS-ATM-LINE but does not start any subordinate PUs or LUs: START BERLIN-ATM-LINE PARIS-ATM-LINE, ONLY 2- 16 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
The STATISTICS Command DSNM Commands The STATISTICS Command Use the STATISTICS command to obtain operational statistics about objects. Some subsystems return statistics on only objects that are up. The STATISTICS command is not appropriate for all object types; refer to the User’s Guide to DSNM Commands for details on this restriction. STATISTICS objectspec [, [, [, [, objectspec ]... hierarchy-modifier ] error-modifier ] RESET ] objectspec is the object specification.
The STATISTICS Command DSNM Commands A sample response to the command is: EXPAND LINE \PARIS.$LHD Current Timestamp: 21 Feb 1992, 16:07:52.044 Last Resetstats Time: 21 Feb 1992, 16:03:36.
The STATUS Command DSNM Commands The STATUS Command Use the STATUS command to obtain the current subsystem status of objects, as obtained from the subsystem. The STATUS command generates more up-to-date information than the INQUIRE command, but the response time can be slower. STATUS objectspec [, [, [, [, [, objectspec ]... hierarchy-modifier ] error-modifier ] state-modifier ] response-modifier ] objectspec is the object specification.
The STATUS Command DSNM Commands The state modifier is ignored if the response modifier has the value of SUMMARY, SUMMARY-BYTYPE, or SUMMARY-BYOBJECT, because these values return totals by subsystem state. If the SUBONLY and SUMMARY modifiers are combined for object types on the lowest level, counter values are 0. (Subordinate objects do not exist; therefore, the summary of their counters is 0.
The STOP Command DSNM Commands The STOP Command Use the STOP command to stop objects. The command causes DSNM to issue the appropriate subsystem commands to stop each object after all current and outstanding operations are complete. If all objects specified in the command are successfully stopped, there is no command response. If the command fails to stop any object, there is a response, listing the objects that were not stopped.
The STOP Command DSNM Commands during which time the objects can be reported by DSNM as in either the DOWN or the PENDING state. Because each subsystem must stop its objects in a predetermined order, the ONLY hierarchy modifier is ineffective with certain object types if their subordinate objects are still up; that is, stopping certain object types forces their subordinates to also be stopped.
The UPDATE Command DSNM Commands The UPDATE Command Use the UPDATE command to modify object attributes in the DSNM object database that control: • • Whether an object is monitored when it appears on the NetStatus display What states cause an object to be highlighted on the NetStatus display The UPDATE command returns a response for only those objects that are not successfully updated. The UPDATE command line must include a MONITOR, NOMONITOR, or ACCEPT parameter.
The UPDATE Command DSNM Commands UNDEFINED, MONITORED, NOT-MONITORED, ACCEPTABLE, and UNACCEPTABLE. There is no default for the highlight modifier. FROM-DISPLAY causes the command to use the names on the NetStatus display instead of resolving them through Distributed Name Service (DNS), thus speeding name resolution. The FROM-DISPLAY parameter is valid only if you are issuing the UPDATE command from the NetStatus command line and all the objects specified in the command appear on the NetStatus screen.
DSNM Commands The UPDATE Command Example The following command replaces the current values of the acceptable states fields for the SNAX PU \BERLIN.$SATM.#ATMCC with the current state of the PU: UPDATE PU \BERLIN.$SATM.#ATMCC, ONLY, ACCEPT Because the command line includes the ONLY modifier, it does not update the object entries for any subordinate LUs.
The UPDATE Command 2- 26 DSNM Commands 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
3 I Process Development Process Scope of This Section This section introduces the conceptual model upon which the I process program’s frame and command thread interactions and supporting library services are based. Also provided are a detailed development model and associated rules for using the I process development software correctly and effectively. The purpose of this section is to: • • • Define central concepts of the I process program structure.
Function of the I Process I Process Development Process You can think of an I process as being a translator from the DSNM language to the language supported by the subsystem CI. Note. This release of the DSNM subsystem interface development software addresses server-type CIs only, which must be started outside the I process. DSNM commands can be categorized by function as follows: • • • Information retrieval commands—return various types of information about objects.
I Process Development Process I Process Program Structure Concepts I Process Program Structure Concepts The following concepts are central to the I process program structure: Frame A frame is a set of compiled procedures supplied by Tandem into which user-written subsystem-specific code is bound to produce an I process that conforms to DSNM protocols.
I Process Program Structure Concepts I Process Development Process Figure 3-2. Relationship Between the Frame and User-Written Procedures I PROCESS I Process Program Frame User-Written Procedures _COMMAND^PROC Command Thread Command CommandThread Thread Procedures Procedure Procedure Subprocedures Subprocedures Subprocedures _STARTUP _COMMAND^ TERMINATION^ PROC _STARTUP^MODE 006 Dispatch Dispatch means invoking a thread for execution.
I Process Development Process I Process Program Structure Concepts Command Context A command context is a collection of data in memory reserved for a particular thread’s exclusive use during its execution. When the frame receives a command, it creates an instance of the command thread and dynamically allocates memory for a command context area that is preserved for the life of the thread. Thread procedures must use memory within their context area.
General Command Processing Scheme I Process Development Process General Command Processing Scheme As an I process developer, you write a set of procedures that, when executed, form a command thread that carries out a DSNM command. The general command processing scheme is listed next. (See Figure 3-3 on page 3-8 for an illustrated example.) 1.
I Process Development Process f. General Command Processing Scheme The thread places the response (possibly empty, depending on the command requirements) into a predefined output object list (defined as part of the command context space). Steps b through f are repeated until the input list is exhausted and the output list represents a complete response to the original DSNM command. During the process, the thread can define its own lists and add members to it for intermediate results. Note.
General Command Processing Scheme I Process Development Process Figure 3-3. Frame/Command Thread Interaction: Processing a DSNM Command DSNM LIBRARY SERVICES I PROCESS PROGRAM FRAME Receive command. Extract command, modifiers, and objects and create input object list. COMMAND THREAD (_COMMAND^PROC) Create instance of command thread ( CALL _COMMAND^PROC ). Create subsystem operation for current object. Present operation to subsystem CI.
The Command Thread Source Environment I Process Development Process The Command Thread Source Environment The source environment in which the command thread is written consists of source definitions (DDL, literals, and defines), global definitions, and external declarations.
The Command Thread Source Environment I Process Development Process STRING .ciname[0:ZDSN^MAX^CICLASS-1] := [“xxxxxxx ”]; STRING .ssname[0:ZDSN^MAX^SUBSYS-1] := [“xxxxxxx ”]; END BLOCK; ?SOURCE KDSNDEFS (IPROCESS^GLOBALS) ?NOLIST, SOURCE EXTDECS0 ( ... ) ?LIST ?SOURCE KDSNDEFS (IPROCESS^EXTDECS) _THREAD^PROC(MYPROC1); FORWARD; _THREAD^PROC(MYPROC2); FORWARD; INT PROC _STARTUP (cx^length, in^lm^length) EXTENSIBLE; INT .cx^length, .
I Process Development Process User-Written Procedures _THREAD^TERMINATION^PROC (_COMMAND^TERMINATION^PROC); BEGIN < clean up thread environment > _END^THREAD^TERMINATION^PROC; ASSIGN Statements Required for Compilation For compilation, you must assign the following subvolumes to be searched: • • $SYSTEM.SYSTEM—or the subvolume on your system that contains EXTDECS0.
The _STARTUP^MODE Procedure I Process Development Process The _STARTUP^MODE Procedure The frame calls_STARTUP^MODE when it begins its startup processing. _STARTUP^MODE performs the following tasks: • • • Retrieves the component name of the subsystem(s) being handled by the I process. Determines whether the I process is running in test mode. Determines whether to use the COMPONENT process parameter value if one appears in the startup message.
I Process Development Process The _STARTUP Procedure The _STARTUP Procedure The frame must supply the lengths of the command context space and the input list member structures for which it allocates memory each time it creates an instance of a thread. _STARTUP declares an initialization procedure that is called by the frame to provide this information before it creates the first instance of the command thread.
Declaring Thread Procedures: _THREAD^PROC and _END^THREAD^PROC I Process Development Process Declaring Thread Procedures: _THREAD^PROC and _END^THREAD^PROC Any procedure that might be dispatched as part of a thread must be declared with _THREAD^PROC and _END^THREAD^PROC: _THREAD^PROC ( procname ); BEGIN < procedure body > _END^THREAD^PROC; _END^THREAD^PROC issues RETURN _RC^WAIT, which returns the thread to the frame until the occurrence of the next event causes it to be redispatched.
I Process Development Process Command Context Space Use _THREAD^TERMINATION^PROC in the following construction: _THREAD^TERMINATION^PROC (_COMMAND^TERMINATION^PROC); BEGIN . . < procedure body > . ! for example, free lists, close the open CI(s) and ! return, leaving the input and output lists for the ! frame CALL _DEALLOCATE^LIST (...); CALL _CLOSE^CI (...); .
Command Context Space I Process Development Process Figure 3-4. Command Context Area For example: Command Context Area struct input^lm^def (*); begin _INPUT^LM^HEADER; ... end; struct output^lm^def (*); begin _OUTPUT^LM^HEADER; ... end; int .ext cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; int .ext in (_INPUT^DEF) := @cx._INPUT; int .ext out (_OUTPUT^DEF) := @cx._OUTPUT; struct command^context^def (*); begin _COMMAND^CONTEXT^HEADER; int .
I Process Development Process Defining the Command Context Space Accessing the Command Context Space _THREAD^CONTEXT^ADDRESS is an INT(32) global variable in which the frame places the extended address of the command context space before each thread dispatch. The thread can access the command context space with a data definition similar to the following example: INT.
The Input Area: _INPUT I Process Development Process The Input Area: _INPUT The input area is the portion of the command context space in which the frame places the command components. _INPUT is the name assigned to the _INPUT^DEF structure generated by _COMMAND^CONTEXT^HEADER. This structure contains the _LIST declarations for the input object list (OBJECTLIST), the action field, and a structure containing the command modifiers.
I Process Development Process The Output Area: _OUTPUT Response modifier (.Z-RMOD): ZDSN^RMOD^BRIEF ZDSN^RMOD^DETAIL Note. SUMMARY response modifiers are handled entirely by the I process frame and are never seen by the command thread itself. Action modifier (.Z-AMOD): ZDSN^AMOD^RESET Flow modifier (.Z-FMOD) Actions and modifiers are described in detail in Section 4, “DSNM Command Requirements.” Accessing the Input Area Use data definitions similar to the following to access the input area: INT .
The Input and Output List Member Structures I Process Development Process The Input and Output List Member Structures In addition to defining the command context area, you must also define the input and output list member structures by specifying a structure template for each, as illustrated in Figure 3-5. The first part of each structure is reserved for use by the frame; the thread defines the rest of the structure.
The Input and Output List Member Structures I Process Development Process Figure 3-5. Object List Member Definitions _INPUT.OBJECTLIST members struct FOBJ struct input^lm^def (*); begin _INPUT^LM^HEADER; ... end; z^hmod z^subsys z^objtype z^objname^occurs z^objname z^manager^occurs z^manager User-defined output list member fields . . . Input Object List _OUTPUT.OBJECTLIST members struct FOBJ struct output^lm^def (*); begin _OUTPUT^LM^HEADER; ...
I Process Development Process Defining the Input List Member Structure: _INPUT^LM^HEADER Defining the Input List Member Structure: _INPUT^LM^HEADER _INPUT^LM^HEADER describes the first part of an input list member. It generates an input list formatted object structure (FOBJ). It is required as part of the input list member definition.
I Process Development Process Working With Lists The following is an example of an output list member structure definition: STRUCT output^list^member^def (*); BEGIN _OUTPUT^LM^HEADER; ... END; The following FOBJ fields must be filled in by the command thread for each object in the output object list according to the specifications for the individual commands (described in Section 4, “DSNM Command Requirements”): Z^RESULT Contains the result code for the object in the response buffer.
Declaring a List: _LIST I Process Development Process Figure 3-6. Logical View of a List _PUSH^LM _POP^LM @last := _LAST^LM ( list ); @previous := _PREDECESSOR^LM ( list, last ); error := _DELETE^LM ( list, @ list-member ); @next := _SUCCESSOR^LM ( list ,first ); @first := _FIRST^LM ( list ); List Member Structure num := _MEMBERSOF^LIST ( list ); length := _SIZE^OF^LM ( list-member ); _PUT^LM _GET^LM 050 Declaring a List: _LIST Use _LIST to declare a list structure.
I Process Development Process Declaring a Pointer to a List: _LISTPOINTER Accessing the First Member of a List: _FIRST^LM Use _FIRST^LM to retrieve the address of the first member of a list. @first-list-member := _FIRST^LM ( list ); Accessing the Last Member of a List: _LAST^LM Use _LAST^LM to retrieve the address of the last (most recent) member of a list.
Scanning a List I Process Development Process Scanning a List The following examples illustrate methods of scanning lists: • This example scans a list forward: @lm := _NULL; WHILE _NOTNULL (@lm := _SUCCESSOR^LM (list,lm) DO BEGIN ... END; • In the next example, the user waits for a new last member to be added to the end of a list by keeping a previous member pointer. After finding a _NULL, @lm is returned to its previous setting.
I Process Development Process Maintaining a List First-In First-Out Processing: _PUT^LM / _GET^LM Use _PUT^LM to allocate memory for a new last member of a list. Use _GET^LM to remove the current first member from a list (the earliest member put on the list). @list-member := _PUT^LM ( list ,[ length ] ,initlength ,[ initdata ] ); @list-member := _GET^LM ( list ,[ length ] ); Last-In First-Out Processing: _PUSH^LM / _POP^LM Use _PUSH^LM to allocate memory for a new last member of a list.
Requesting Status About a List I Process Development Process Joining Two Lists: _JOIN^LIST Use _JOIN^LIST to append all members of a source list to a destination list. When two lists are joined, data is not moved in memory. The source list is empty afterwards. error := _JOIN^LIST ( dest-list ,source-list ); Requesting Status About a List Use the following library services to get information about lists.
I Process Development Process Initializing Object List Members: _FOBJECT^INIT You can produce new objects from objects on the input list in two ways: 1. The input object is a subsystem object, and new object names are subordinate objects produced as a result of processing a hierarchy modifier (HMOD). 2. The input object is an wild card (*), and new object names are produced as a result of expanding the wild card.
Initializing Object List Members: _FOBJECT^INIT I Process Development Process The following fields from the source FOBJECT structure are copied to new-fobject when the parent-fobject argument is supplied: Z^SUBSYS Z^MANAGER^OCCURS Z^MANAGER Z^OBJTYPE, Z^OBJNAME, and Z^OBJNAME^OCCURS are set to null values (zero or blanks, as appropriate). It is your responsibility to supply values for the Z^OBJTYPE and Z^OBJNAME fields. It is not necessary to fill in Z^OBJNAME^OCCURS, except for your own use.
I Process Development Process Initializing Object List Members: _FOBJECT^INIT Example In the following example, an output object is initialized. The output object is derived by processing its source input object; its status, object type, and object name are filled in: STRUCT input^lm^def (*); BEGIN _INPUT^LM^HEADER; ... END; STRUCT output^lm^def (*); BEGIN _OUTPUT^LM^HEADER; ... END; STRUCT command^context^def (*); BEGIN _COMMAND^CONTEXT^HEADER; INT .EXT inobj (input^lm^def); INT .
Adding Text Items to an Output Object: _APPEND^OUTPUT I Process Development Process Adding Text Items to an Output Object: _APPEND^OUTPUT For some commands, text and other variable-length items must be appended to the output object with _APPEND^OUTPUT: error := _APPEND^OUTPUT ( output-list-member ,type ,[ header ] ,[ header-len ] ,[ body ] ,[ body-len ] ); Text items are described fully under the individual command descriptions in Section 4, “DSNM Command Requirements.
I Process Development Process Example: List Processing Library Services STRUCT command^context^def (*); BEGIN _COMMAND^CONTEXT^HEADER; INT .EXT inobj (input^lm^def); INT .EXT outobj (output^lm^def); END; !Thread proc locals! INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .EXT in (input^lm^def) := @cx._INPUT; INT .EXT out (output^lm^def) := @cx._OUTPUT; ... ! Get the next input object IF _ISNULL (@cx.inobj := _GET^LM (in.OBJECTLIST)) THEN ...
Suspending and Dispatching Thread Procedures I Process Development Process IF (error := _FOBJECT^INIT (cx.outobj.FOBJ,, cx.inobj.FOBJ)) THEN ... ; cx.outobj.FOBJ.Z^RESULT := ; cx.outobj.FOBJ.Z^OBJTYPE ':=' ; cx.outobj.FOBJ.Z^OBJNAME ':=' ; _RELEASE^OUTPUT (cx.outobj); ...
Dispatching Thread Procedures: Events I Process Development Process Dispatching Thread Procedures: Events A thread dispatch is initiated by an event, such as the completion of a CI communication. Events can be generated by the frame or by the thread itself: • • Events generated by the frame occur singly, with one dispatch per event. Events generated by the thread occur together, immediately after the next return to the frame and before any frame-generated events.
Declaring Utility Procedures: _RC^TYPE I Process Development Process Declaring Private Thread Events: _PRIVATE^THREAD^EVENT _PRIVATE^THREAD^EVENT declares events, the values of which are different from any frame-generated event values, with meanings private to the thread. _PRIVATE^THREAD^EVENT ( num ); num is a number in the range 0 through 7.
I Process Development Process State Management In the following example, a thread procedure calls an _RC^TYPE procedure. The called procedure returns a frame return code, which is interpreted by the calling procedure. _RC^TYPE PROC process^object ( ... ); BEGIN . . END; _THREAD^PROC (_COMMAND^PROC); BEGIN _RC^TYPE obj^rc; . . obj^rc := process^object ( ... ); IF obj^rc <> _RC^NULL THEN RETURN obj^rc; . .
Determining Which Event(s) Caused the Current Dispatch I Process Development Process Determining Which Event(s) Caused the Current Dispatch _REAL^LAST^EVENTS and _LAST^EVENTS allow the thread to determine which event(s) caused the current dispatch. _REAL^LAST^EVENTS Each time the command is dispatched, _REAL^LAST^EVENTS is set to contain the event(s) that caused the current dispatch. Each bit represents a different event.
I Process Development Process Altering the Current Thread Procedure and Thread State Altering the Current Thread Procedure and Thread State When the frame dispatches the thread, it calls the current thread procedure.
Altering the Current Thread Procedure and Thread State I Process Development Process Determining and Setting the Current Thread State: _THREAD^STATE The frame sets the thread state to _ST^INITIAL when it creates a thread. Subsequently, you may set the thread state as desired; the frame never uses it again. The current thread state can be tested or set with _THREAD^STATE. The following example tests the current state of the thread: CASE _THREAD^STATE OF BEGIN _ST^INITIAL -> ... OTHERWISE -> ...
I Process Development Process Altering the Current Thread Procedure and Thread State PROC^X calls PROC^Y in STATE^B by: • • • Setting its return state to STATE^A. Saving the old current thread procedure and state values, and setting new current thread procedure and thread state values. Signaling an event and returning to the frame to dispatch the new thread procedure PROC^Y in the new state STATE^B.
I Process Development Process Altering the Current Thread Procedure and Thread State Figure 3-7. Altering Current Thread Procedure and Thread State Values Current PROC^X _ST^INITIAL PROC^X of command thread executing in _ST^INITIAL. _THREAD^STATE := STATE^A; Current PROC^X STATE^A PROC^X executing in STATE^A.
I Process Development Process Altering the Current Thread Procedure and Thread State Dispatching a New Thread Procedure: _DISPATCH^THREAD _DISPATCH^THREAD returns to the frame and causes a new dispatch. _DISPATCH^THREAD does not save any information about the procedure from which it was invoked.
I Process Development Process Altering the Current Thread Procedure and Thread State Figure 3-8. Dispatching New Thread Procedures Current PROC^X _ST^INITIAL PROC^X of command thread executing in _ST^INITIAL. _DISPATCH^THREAD (@PROC^Y, STATE^A, EVENT^B); Current PROC^Y STATE^A PROC^Y of command thread executing in STATE^A. _REAL^LAST^EVENTS EVENT^B _SAVE^THREAD^AND^DISPATCH (@PROC^Z, STATE^B, EVENT^C); Current PROC^Z STATE^B PROC^Y STATE^A PROC^Z of command thread executing in STATE^B.
I Process Development Process CI Communications Frame Services The frame transmits CI messages and sets timeout intervals for the command thread. To request a frame service, such as CI communication, the command thread calls a library procedure and eventually returns to the frame to wait for the event signaling the completion of the service. The frame generates a service completion event (_EV^IODONE or _EV^TIMEOUT) at the completion of each service and then redispatches the thread.
CI Communications I Process Development Process The definition of the _CI^DEF-defined structure is: DEFINITION ZDSN-DDL-PCLASS-CONFIG. 02 Z-PCLASS TYPE ZDSN-DDL-PCLASS. 02 Z-PUBLIC-NAME-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-PUBLIC-NAME TYPE ZDSN-DDL-PARAMNAME. 02 Z-FLAGS TYPE ZSPI-DDL-ENUM. 02 Z-PNAME-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-PNAME TYPE ZDSN-DDL-PNAME. 02 Z-MAX-PROCESSES TYPE ZSPI-DDL-INT. 02 Z-OPEN-PARAMS. 03 Z-DEFAULT-QUALIFIER TYPE ZDSN-DDL-PQUAL. 03 Z-NOWAIT-DEPTH TYPE ZSPI-DDL-INT.
I Process Development Process CI Communications Declaring a CIID Structure: _CI^ID To access a CI, first use _CI^ID to declare a structure, referred to as a “CIID structure.” A later call to _OPEN^CI causes information about the CI to be stored in the CIID structure. _CI^ID ( ciid ); ciid is the name (a valid TAL identifier) of the CIID structure by which an open CI can be referred. Note.
Accessing Information About a CI Communication I Process Development Process When the communication is complete, the frame dispatches the thread with the event _EV^IODONE. Canceling a CI Communication Request: _CANCEL^SEND^CI Use _CANCEL^SEND^CI to cancel an outstanding CI communication request: error := _CANCEL^SEND^CI ( [ tag ] ); The frame cancels any outstanding _SEND^CI operations when the thread terminates.
I Process Development Process Accessing Information About a CI Communication The Most-Recently Completed CI Communication: _LAST^CI^ID _LAST^CI^ID is a field within the command context space giving the CI involved in the CI communication terminated by the last _EV^IODONE event. Its type is _CI^IDPOINTER. _CI^IDPOINTER (mgr); INT .EXT cx(command^context^def) = _THREAD^CONTEXT^ADDRESS; IF _ON (_LAST^EVENTS, _EV^IODONE) THEN BEGIN @mgr := cx._LAST^CI^ID; IF _CI^LASTERROR (mgr) ! check for errors THEN ...
Timeout Intervals I Process Development Process File Number: _CI^FILENUM _CI^FILENUM is the type INT file number of the CI involved with the most-recently completed communication. filenumber := _CI^FILENUM ( ciid ) Timeout Intervals The command thread may create a pause by arranging for a future timeout event and then returning to the thread to wait for it.
I Process Development Process Reporting Errors . . . IF _ON (_LAST^EVENTS, _EV^TIMEOUT) THEN BEGIN @time^info := cx._LAST^TIMEOUT^TAG; CALL _DELETE^LM (cx.worklist, @time^info); END; _LAST^TIMEOUT^TAG is a type INT(32) expression. Canceling a Timeout Request: _CANCEL^TIMEOUT Cancel an outstanding timeout with _CANCEL^TIMEOUT: error := _CANCEL^TIMEOUT ( [ tag ] ); tag is a type INT(32) expression.
Reporting Errors to the Frame • • I Process Development Process If appropriate, generate an EMS event (see “Reporting Errors to EMS” for guidelines). Return to the frame with an appropriate _RC^ABORT error to describe the error. The _EV^CANCEL event should be handled like an error except that it is a normal thread termination (return code _RC^STOP is appropriate).
I Process Development Process • Reporting Errors to EMS ZDSN^ERR^OBJ^NOT^FOUND Use this value to report an object unknown to the subsystem. No result text should be included. • ZDSN^ERR^SUBSYSTEM^ERR Use this value to report all other subsystem errors. The error should be described as result text. Command-Terminating Errors If an error causes a command to terminate, the command thread must clean up its resources.
Overview of the Library Services I Process Development Process Overview of the Library Services Table 3-1 lists the library services that support the I process development model. Table 3-1.
I Process Development Process Overview of the Library Services Table 3-1. Summary of I Process Development Library Services (page 2 of 6) Function Arguments Description Appending text error := _APPEND^OUTPUT ( output-list-member, type ,[ header ] ,[ header-len ] ,[ body ] ,[ body-len ] ); Appends text and other variable-length items to an output object. Releasing _RELEASE^OUTPUT ( output-list-member ); Releases a member of the output list to the frame.
Overview of the Library Services I Process Development Process Table 3-1. Summary of I Process Development Library Services (page 3 of 6) Function Arguments Description Parameter retrieval procedures @ci-config := _ADD^CI (ciname ,[ error ] ,[ error-filename ] ); Fills in _CI^DEF-defined structure with CI configuration information. @ss-config := _ADD^SUBSYS (ssname ,[ error ] ,[ error-filename ] ); Fills in _SUBSYS^DEF-defined structure with subsystem and object type configuration information.
I Process Development Process Overview of the Library Services Table 3-1. Summary of I Process Development Library Services (page 4 of 6) Function Arguments Description Processing @lm := _PUT^LM (list ,[ length ] , initlength ,[ initdata ] ); @lm := _GET^LM (list ,[ length ] ) FIFO processing (first in, first out): adds new last member; removes current first member.
Overview of the Library Services I Process Development Process Table 3-1. Summary of I Process Development Library Services (page 5 of 6) Function Arguments Description CI Communication Given that INT .EXT ci-config (_CI^DEF) ... Declarations _CI^ID ( ciid ); Declares CIID structure where information about an open CI is stored. _CI^IDPOINTER (ciid ); Declares (extended) pointer to a CIID structure.
I Process Development Process Overview of the Library Services Table 3-1. Summary of I Process Development Library Services (page 6 of 6) Function Arguments Description Frame-defined input/output areas _INPUT^DEF Structure template that defines the input area of the command context space. _INPUT Name assigned to the _INPUT^DEF structure by _COMMAND^CONTEXT^HEADER. _OUTPUT^DEF Structure template that defines the output area of the command context space.
Overview of the Library Services 3- 60 I Process Development Process 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
4 DSNM Command Requirements Scope of This Section This section defines the requirements for carrying out DSNM operations. It specifies what information is sent to the command thread and what information must be returned for each command so that the frame can create a DSNM-formatted response to return to the requester. Command Flow The typical flow for a DSNM command is from a user to the DSNM command server, and then to one or more I processes.
Action to be Performed DSNM Command Requirements Action to be Performed The action to be performed is determined by the value in the _INPUT.ACTION field in the command context space. The command thread must be able to translate the following DSNM operations into an equivalent subsystem-specific command or command sequence: ZDSN^ACTION^ABORT Brings objects to a nonoperational state, without waiting for outstanding operations to complete.
Object List Modifiers DSNM Command Requirements These modifiers fall into the following categories: • • • Object list modifiers, which limit or expand the scope of the original input object list (HMOD and SMOD). Response modifiers, which determine the amount and type of information returned for each object in the output object list (RMOD and EMOD). The action modifier, which indicates that statistics be reset (AMOD).
Object List Modifiers DSNM Command Requirements In addition to the HMOD value in the MOD structure supplied with the command (MOD.Z^HMOD), there may also be an HMOD value in the FOBJECT structure associated with each input list object (FOBJ.Z^HMOD). When both are present, the HMOD in the object structure overrides the HMOD command modifier. Table 4-2 summarizes HMOD usage. Table 4-2. HMOD Usage FOBJ.Z^HMOD MOD.
Response Modifiers DSNM Command Requirements When SMOD is specified, only objects in UP/GREEN, DOWN/RED, and PENDING/YELLOW states are included. So, for example, a STATUS command with a NOT^RED SMOD value should not include UNDEFINED or UNKNOWN objects in the response. Note. It is the responsibility of the command thread to map the set of states supported by the subsystem into the set of DSNM states (see “Object States” on page 4-7). Error reporting is independent of SMOD.
Response Modifiers DSNM Command Requirements The Error Modifier (_INPUT.MOD.Z^EMOD) The error modifier (EMOD) controls how much information to return if a subsystem error occurs during command processing. EMOD is valid for all DSNM commands except AGGREGATE; its values have the following meanings: ZDSN^EMOD^BRIEF Append a single line of text (ZDSN^VTY^RESULTTEXT) to describe the ZDSN^ERR error code in the Z^RESULT field to members on the output object list that generate an error. This is the default.
Object States DSNM Command Requirements Action Modifiers ZDSN^AMOD^RESET in the _INPUT.MOD.Z^AMOD field indicates that statistics should be reset after being reported. The Action Modifier (_INPUT.MOD.Z^AMOD) The command thread must support the resetting of statistics as indicated by the following action modifier: ZDSN^AMOD^RESET Reset subsystem statistics after reporting (valid for STATISTICS command only).
The Input Object List DSNM Command Requirements In addition to the previous states, an object may not be configured, or it may be configured but its state cannot be determined (because a manager is not running or the object is not secured correctly, for instance). For these cases, the following DSNM states are provided: ZDSN^STATE^UNDEFINED Object is not defined in the subsystem. An error could have been made, either in configuring the subsystem or entering the object name.
The User Area: Intermediate Lists DSNM Command Requirements Z^OBJNAME^ OCCURS Is an INT field that contains the length of the object name. Z^OBJNAME Is a structure (defined by ZDSN^DDL^OBJNAME^DEF) that contains the object name. If the subsystem permits it, the object name may be *, meaning all objects of the object type specified (under the manager specified, if any). Z^MANAGER^ OCCURS Is an INT field that contains the length of the manager name. If a manager is not present, Z^MANAGER^OCURS is 0.
The Output Object List DSNM Command Requirements The Output Object List The output object list is built by the command thread. Each member includes a formatted object structure named FOBJ (defined by ZDSN^DDL^FOBJECT^DEF) that describes one object to which the command was applied. Depending on the command, and the hierarchy, state, and error modifiers, a single input list object may produce many output objects (which may or may not include the original input list object), or no output objects at all.
DSNM Command Requirements Command Requirements Command Requirements The DSNM commands are often needed in daily operations and can be applied to widely diverse objects. For the most part, subsystems support commands equivalent to the DSNM commands for their objects.
The ABORT Command DSNM Command Requirements The ABORT Command ABORT issues the subsystem command(s) that immediately bring objects to a nonoperational state without waiting for outstanding operations to finish. (A nonoperational state is the subsystem state equivalent to the DSNM state ZDSN^STATE^DOWN or ZDSN^STATE^RED.) Note. If the subsystem makes no distinction between stopping objects gracefully and otherwise, the DSNM STOP and ABORT commands perform the same operation.
DSNM Command Requirements The AGGREGATE Command The AGGREGATE Command AGGREGATE issues the subsystem command(s) that return the current operational status of objects. This command summarizes the operational status of all objects in a subsystem. If the subsystem employs a manager, the summary is for all objects controlled by the manager. If there is no manager, Z^MANAGER^OCCURS is 0. For the input list object, only the fields Z^SUBSYS, Z^MANAGER^OCCURS and Z^MANAGER are relevant.
The AGGREGATE Command DSNM Command Requirements If an error occurs such that the subsystem or a manager cannot be reached to carry out the AGGREGATE command, return one output object for that input object in the ZDSN^EMOD^BRIEF format. If necessary, append one line of ZDSN^VTY^RESULTTEXT, further describing the error.
DSNM Command Requirements The INFO Command The INFO Command INFO issues the subsystem command(s) that return configuration information for objects. Valid Modifiers HMOD and EMOD. SMOD is not supported for the INFO command and should be ignored if present. Output Object Requirements Return one output object for each hierarchically derived input list object (unless Z^EMOD = ZDSN^EMOD^SUPPRESS, which suppresses the reporting of objects that cause subsystem errors).
The START Command DSNM Command Requirements The START Command START issues the subsystem command(s) to bring objects to an operational state (the subsystem state equivalent to the DSNM state ZDSN^STATE^UP or ZDSN^STATE^GREEN). Valid Modifiers HMOD, EMOD, SMOD. RMOD does not apply and should be ignored if present. Output Object Requirements Commands to start subsystem objects should be issued for objects obtained by applying the hierarchy (HMOD) and state (SMOD) modifiers to each input list object.
DSNM Command Requirements The STATISTICS Command The STATISTICS Command STATISTICS issues the subsystem command(s) that return operational statistics for objects. Valid Modifiers HMOD, EMOD, AMOD. AMOD = ZDSN^AMOD^RESET (meaning statistics counters are to be reset after being reported). SMOD is not supported and should be ignored if present.
The STATUS Command DSNM Command Requirements The STATUS Command STATUS issues the subsystem command(s) that return the current operational status of objects. One output object should be returned for each subsystem object obtained by applying the hierarchy (HMOD) and state (SMOD) modifiers to each input list object. Valid Modifiers HMOD, EMOD, SMOD, RMOD.
DSNM Command Requirements The STATUS Command The resulting display might include something like the following. The text in bold is ZDSN^VTY^TEXT appended to the output object. . . SNAX LU \WYJ.$STLR.
The STOP Command DSNM Command Requirements The STOP Command STOP issues the subsystem command(s) that bring objects to a nonoperational state (the subsystem state equivalent to the DSNM state ZDSN^STATE^DOWN or ZDSN^STATE^RED). Objects should be brought down gracefully if the subsystem supports it, allowing current operations to terminate normally. Note. If the subsystem makes no distinction between stopping objects gracefully and otherwise, the DSNM STOP and ABORT commands perform the same operation.
5 DSNM Process Startup Functions Scope of This Section DSNM processes call a startup procedure as the first step in the main procedure. Typically, the startup procedure reads parameters via library calls, and then continues with other process-specific initialization. Processes retrieve process parameters and configuration parameters from either the startup message or the DSNMCONF file, depending on how the system is configured and how the parameter-retrieval procedures are called.
Process Parameters DSNM Process Startup Functions Process Parameters The standard DSNM process parameters accepted from the startup message are discussed next. (TESTMODE, CONFIG, STARTUP, and DEBUG are used for development testing only.) DSNM env-name specifies the $SYSTEM.SYSTEM.DSNM section name to be used by this process. The process uses the environment defined in ?SECTION env-name in $SYSTEM.SYSTEM.DSNM. If both the DSNM and CONFIG parameters are omitted, the unnamed section (blank) of $SYSTEM.
DSNM Process Startup Functions DSNM Configuration Parameters To start an I process for testing with DSNMCom (I process test utility), using sitespecific configuration parameters in $DSNM.NETW.DSNMCONF and I-processspecific configuration parameters in $DSNM.IDEV.DSNMIDEV, use the TESTMODE and CONFIG process parameters in an explicit RUN command. For example: RUN $DSNM.IDEV.SPIFI/NAME $SPFI,NOWAIT/TESTMODE 1, & CONFIG $DSNM.NETW.DSNMCONF $DSNM.IDEV.
Parameter Types and Search Criteria DSNM Process Startup Functions Parameter Types and Search Criteria The parameter retrieval library functions retrieve parameter values from the startup message or the DSNMCONF file, according to the search criteria specified in the arguments passed to the procedures. (See the syntax descriptions of the procedures in “Parameter Retrieval Library Services” on page 5-6.
Global Parameters and Search Patterns DSNM Process Startup Functions Local General Parameters A local general parameter is any instance of this parameter. It may be for this component, for the class as a whole (if component is blank), or for any class (if both class and component are blank).
Parameter Retrieval Library Services DSNM Process Startup Functions Global General Parameters A global general parameter is all instances of this parameter. It may be for this component, for the class as a whole (if component is blank), or for any class (if both class and component are blank).
DSNM Process Startup Functions • • Parameter Retrieval Library Services Uses the COMPONENT value passed from _STARTUP^MODE (or the startup message, if indicated) to retrieve standard process parameters and configuration parameters into predefined structures. Supplies appropriate defaults. Note. The command thread also has access to the information retrieved by the frame; see the next two subsections for information on accessing _PROCESS^PARAMS and _DSNMCONF^PARAMS parameters. 3.
Accessing Standard Process Parameters: _PROCESS^PARAMS DSNM Process Startup Functions Accessing Standard Process Parameters: _PROCESS^PARAMS As part of its startup processing, the frame retrieves values for these parameters and fills in a structure declared by _PROCESS^PARAMS. The command thread may then access these values for its own use. The structure declared by _PROCESS^PARAMS is defined as follows: DEFINITION ZDSN-DDL-PROCESS-PARAMS. 02 Z-CLASS-OCCURS TYPE ZSPI-DDL-UINT.
DSNM Process Startup Functions Retrieving Non-Standard Process Parameters: _GET^PROCESS^PARAM The structure declared by _DSNMCONF^PARAMS is defined as follows: DEFINITION ZDSN-DDL-DSNMCONF-PARAMS. 02 Z-DSNM-MANAGER-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-DSNM-MANAGER TYPE ZDSN-DDL-MANAGER. 02 Z-SWAPVOL-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-SWAPVOL TYPE ZDSN-DDL-OBJNAME. 02 Z-SEGPAGES TYPE ZSPI-DDL-INT2. 02 Z-SEGEXT. 03 Z-PRIMARY TYPE ZSPI-DDL-INT. 03 Z-SECONDARY TYPE ZSPI-DDL-INT.
Retrieving Nonstandard Configuration Parameters: _GET^PARAM DSNM Process Startup Functions input maxlen INT is the maximum number of bytes that can be returned in paramvalue. output len INT is the number of bytes returned in paramvalue. Retrieving Nonstandard Configuration Parameters: _GET^PARAM You can call _GET^PARAM in your _STARTUP procedure to retrieve configuration parameter values that are not part of the standard set stored in the _DSNMCONF^PARAM structure.
DSNM Process Startup Functions Retrieving Nonstandard Configuration Parameters: _GET^PARAM input paramtype INT indicates how restrictive the search criteria is: _COMPONENT^PARAM Component parameters are instances of a parameter specific to this component and class. _CLASS^PARAM Class parameters are instances of a parameter specific to this class. If component is blank, it is specific to the class as a whole. _GENERAL^PARAM General parameters are any instance of this parameter.
Retrieving Subsystem Configuration Parameters DSNM Process Startup Functions input maxlen INT the maximum length, in bytes, that can be returned in paramvalue. output len INT the actual length, in bytes, of the value returned in paramvalue. If len < maxlen, the remainder of paramvalue is blank-filled. error-filename output STRING .EXT ! ZDSN^DDL^OBJNAME^DEF ! is the name of the configuration file associated with the returned error value.
6 Conf DSNM Scope of This Section This section contains the steps necessary to configure a subsystem and its associated I process into DSNM. More configuration and management details, including an extended list of the DSNM process class configuration parameters, can be found in the Distributed Systems Management Solutions (DSMS) System Management Guide.
The $SYSTEM.SYSTEM.DSNM File • The following are changes to the processing of the DSNM configuration file: • • • • Configuring a New Subsystem Into DSNM If no DSNM configuration file is specified, each DSMS process uses the file named DSNMCONF, located on the same subvolume as the object file of the process. If a nonexistent DSNM configuration file is specified (explicitly or by default), the DSNM processes behave as if the file is present, but empty.
The $SYSTEM.SYSTEM.DSNM File Configuring a New Subsystem Into DSNM The format of $SYSTEM.SYSTEM.DSNM is as follows: [ ?SECTION ] [ CONFIG [ FILE ] filename [ filename [ filename ] ] ] [ STARTUP [ PARAMS ] { YES | NO } ] [ ?SECTION env-name [ CONFIG [ FILE ] filename [ filename [ filename ] ] ] [ STARTUP [ PARAMS ] { YES | NO } ] ] . . . ?SECTION env-name names the DSNM environment. Each section in $SYSTEM.SYSTEM.DSNM defines a separate environment. The first section in $SYSTEM.SYSTEM.
Format of the DSNMCONF File Configuring a New Subsystem Into DSNM A CONFIG statement search list may specify nonexistent files; this is not an error. A nonexistent file is treated as if it were present but empty. It is ignored, and the search continues with the next configuration file. This is also true of the default DSNM configuration file (objsubvol.DSNMCONF), if there is no CONFIG statement for an environment. The Tandem configuration file $SYSTEM.SYSTEM.
SUBSYSTEM Class Records Configuring a New Subsystem Into DSNM Searching schemes provide various ways for library procedures to retrieve values from these files. See Section 5, “DSNM Process Startup Functions,” for more information on searching schemes. DSNMCONF Records Relevant to I Processes The classes of DSNM configuration parameters of concern for I process development are SUBSYSTEM, SUBSYSTEM-INTERFACE-CONFIG, and CI-CONFIG. These are described in detail in the following subsections.
SUBSYSTEM Class Records Configuring a New Subsystem Into DSNM subsystem. Objects are started in increasing rank order and stopped in decreasing order. The default value is 0, indicating that the rank of the object is 1 greater than its parent’s rank (this means that the object is one level below its parent in the subsystem object hierarchy). Nonzero relative ranks may be used to specify starting (increasing) and stopping (decreasing) orders for subordinates of the same parent type.
SUBSYSTEM Class Records Configuring a New Subsystem Into DSNM DEVICETYPE DEVICETYPE is the NonStop Kernel device type and subtypes, if applicable, for objects in the subsystem. Class Component Parameter Value Formats SUBSYSTEM subsystem type [subtype ... [subtype ] ] DEVICETYPE Default: None. Considerations: Up to eight subtypes are permitted. FLAGS FLAGS indicates how object names for the subsystem are specified and resolved.
SUBSYSTEM Class Records Configuring a New Subsystem Into DSNM [NOT] RESOLVE-SUBOBJ-WITHOUT-DNS indicates whether the subordinate object is unique within a subsystem, and it is not necessary for DNS object name resolution. [NOT] [NOT] [NOT] [NOT] DUMMY-DNS-MGR DUMMY-DNS-MANAGER MGR-IN-DNS-IS-DUMMY MANAGER-IN-DNS-IS-DUMMY indicates whether a manager name in DNS for the subsystem is used only to determine the Tandem node on which the object is located. The DNS manager name is ignored.
process-class-CONFIG Records Configuring a New Subsystem Into DSNM subsystem-MANAGER This is the name of the subsystem manager process, if the subsystem uses a single fixed manager process for each Tandem node. Class Component Parameter Value Formats SUBSYSTEM subsystem unqualified-filename subsystem-MANAGER Default: None.
process-class-CONFIG Records • Configuring a New Subsystem Into DSNM SUBSYSTEM-INTERFACE-CONFIG Specifies fixed subsystem interface process configuration parameters (as opposed to site-specific configuration information contained in SUBSYSTEM-INTERFACE class records). • CI-CONFIG Specifies control interface (subsystem management process or public interface management process) configuration parameters.
process-class-CONFIG Records Configuring a New Subsystem Into DSNM OBJECT-FILE OBJECT-FILE is the program file of a process in the process class. Class Component Parameter Value Formats process-class-CONFIG component-name OBJECT-FILE [$vol.][subvol.]file Default: None. Individual users of the class may provide their own defaults. For Tandem processes accessing subsystem managers, the default volume and subvolume is $SYSTEM.SYSTEM and $SYSTEM.SYSnn if the file cannot be found in $SYSTEM.SYSTEM.
Adding Subsystem Objects to the DNS Database Configuring a New Subsystem Into DSNM OPEN-PARAMS OPEN-PARAMS specifies values to be used when the process class is opened. Class Component Parameter Value Format process-class-CONFIG component-name OPEN-PARAMS [ QUALIFIER defaultqualifier ] [ , NOWAIT[-DEPTH] number ] [ , OPEN-TIMEOUT number ] QUALIFIER default-qualifier is the qualifier added to the process name when the process is opened for communication. The default is #ZSPI.
Configuring a New Subsystem Into DSNM Defining an I Process as a Pathway Server are in a text file named ZCPWDSMS (if your installation includes NetStatus) or ZCPWDSNM (if it does not). The following are settings for a Pathway server: RESET SERVER Resets values for all server class attributes to PATHMON defaults. SET SERVER AUTORESTART {0..32767}; number of times PATHMON attempts to restart server process after an abnormal termination. Default is 0. SET SERVER PRI {1..
Defining an I Process as a Pathway Server Configuring a New Subsystem Into DSNM Defining server class configurations is described in detail in the Pathway System Management Reference Manual, if you are running NonStop Kernel release D30.01, or in the NonStop TS/MP and Pathway System Management Guide, if you are running NonStop Kernel release D30.02 or later.
7 DSN Scope of This Section This section describes DSNMCom, the I process test utility. It provides the syntax descriptions for the DSNMCom commands and parameters. What is DSNMCom? DSNMCom is a user interface to DSNM. It enables you to bypass NetCommand and send DSNM commands directly to a started process (such as a command server or an I process). This lets you test your I process without having to set up a DSNM environment. DSNMCom must be licensed before you can use it.
DSNMCom Command Syntax DSNMCom: The I Process Test Utility run-option is any run option for the TACL RUN command. Run options must be separated by commas and set off in the command line by slashes (/). See the TACL Reference Manual for descriptions of valid run options. Two run options most often used with DSNMCom are: IN filename OUT filename IN filename causes DSNMCom to read and execute commands located in the specified file.
DSNMCom: The I Process Test Utility Running DSNMCom Interactively $process-name is the name of the process to which DSNM sends commands. If you omit $process-name, you must open the process with the DSNMCom OPEN command before issuing any DSNM commands (see “The DSNMCom Commands” on page 7-5). $process-name must be preceded by a comma if you specify either DSNM or CONFIG with a blank value. command is either one of the DSNMCom commands listed in Table 7-1, or a DSNM command.
Running DSNMCom From an Input File DSNMCom: The I Process Test Utility Running DSNMCom From an Input File Use the IN file name option with the RUN command to provide DSNMCom with a set of commands to execute. For example, to execute a set of DSNM commands in file EXCMDS, using the configuration file pointed to in section TEST of $SYSTEM.SYSTEM.DSNM, type: > DSNMCOM /IN EXCMDS/ DSNM TEST $process-name . DSNM command output .
DSNMCom: The I Process Test Utility EXIT Command Setting Security Parameters in DSNMCom To set security parameters in DSNMCom, use the DSNMCom SET command. To display the current settings before setting or changing them, use the DSNMCom SHOW command, followed by the parameter name. The SHOW command without a parameter name displays the current settings of all these parameters. The security parameters are discussed with the DSNMCom SET command definition, later in this section.
FC Command DSNMCom: The I Process Test Utility Considerations • • • The DSNMCom process terminates when it reads the end of file (EOF) of an input file: you do not have to end an input command file with an EXIT command. Entering Ctrl/Y at the terminal is the same as EOF. If you type Ctrl/Y at the DSNMCom prompt, DSNMCom terminates. The DSNMCom QUIT command is synonymous with the EXIT command. FC Command FC (fix command) allows you to modify and resubmit the last command line entered.
DSNMCom: The I Process Test Utility SET Command OPEN Command The OPEN command opens the specified process. OPEN $process-name $process-name is the name of the process to which you want to send DSNM commands. Consideration A previously opened process (if any) is closed upon successful completion of the OPEN command. QUIT Command The QUIT command closes all files and terminates DSNMCom; it is synonymous with the EXIT command. QUIT Consideration See the EXIT command considerations.
SET Command DSNMCom: The I Process Test Utility The values of paramname and paramvalue appear in Table 7-2, which lists the DSNMCom SET parameters. Table 7-2. DSNMCom SET Parameters Parameter Function Default COMMAND-CHAR Required first character of each line that contains a DSNMCom command or a comment (except for the FC command). . (period) COMMENT-CHAR Character that must follow COMMAND-CHAR for a comment line. .
DSNMCom: The I Process Test Utility SET Command COMMENT-CHAR COMMENT-CHAR is the character that must follow COMMAND-CHAR for the remainder of the line to be ignored (to be interpreted as a comment). When setting COMMENT-CHAR, enter the new character without quotes. For example, to set the comment character to the slash (/) use the following: .SET COMMENT-CHAR / After DSNMCom processes this command, COMMENT-CHAR becomes the slash (until the next setting of this character or a DSNMCom RESET command).
SHOW Command DSNMCom: The I Process Test Utility When SEND-SECINFO is FALSE, DSNMCom sends logon information (ZDSN^TKN^LOGON^INFO) in the same manner as an external DSNM requester (such as NonStop NET/MASTER). Logon information is only sent if parameter USER is set. If you are testing an I process or a secondary command server, use TRUE for SEND-SECINFO. If you are testing a primary command server, use FALSE for SEND-SECINFO.
DSNMCom: The I Process Test Utility Executing DSNM Commands Executing DSNM Commands Any command you enter from within DSNMCom other than CLOSE, EXIT, FC, HELP, OPEN, QUIT, RESET, SET, or SHOW is assumed to be a DSNM command. You can send DSNM commands directly from the DSNMCom RUN command line. For example: > DSNMCOM CONFIG $DSNM.IDEV.
DSNMCom Messages DSNMCom: The I Process Test Utility DSNMCom Messages DSNMCom produces the following messages, which are displayed on the OUT listing device. ERROR -- no server open: use OPEN Cause. You tried to issue a DSNM command without first opening a process. Effect. You are returned to the DSNMCom prompt. Recovery. Use the OPEN command to open a started process; then resubmit the command. ERROR -- Invalid process name Cause. You provided an invalid process name to DSNMCom. Effect.
DSNMCom: The I Process Test Utility DSNMCom Messages OPEN ERROR nn ON filename Cause. DSNMCom was unable to open the specified file. Effect. If the error occurred on the input or output file, DSNMCom abnormally ends after writing a brief description of the error to the home terminal. If the error occurred on the process file, the process file remains closed; any previously opened process file remains open. Recovery.
DSNMCom Messages DSNMCom: The I Process Test Utility ERROR -- unrecognized text following command Cause. You provided text that is not recognized or supported after the DSNMCom command. Effect. The command is not executed. Recovery. Correct and reissue the command. ERROR -- expecting one of: ON, OFF, TRUE, FALSE, YES or NO Cause. You provided a parameter value that is not recognized or supported. Effect. The command is not executed. Recovery. Correct and reissue the command.
DSNMCom: The I Process Test Utility DSNMCom Messages ERROR -- Unable to obtain userid Cause. Userid is out of bounds or there is an I/O error on $SYSTEM.SYSTEM.USERID. Effect. The command is not executed. Recovery. Check USERID or contact your system manager. ERROR -- Unable to obtain username Cause. Username is out of bounds or there is an I/O error on $SYSTEM.SYSTEM.USERID. Effect. The command is not executed. Recovery. Check USERNAME or contact your system manager. ERROR -- non-existent user Cause.
DSNMCom Messages DSNMCom: The I Process Test Utility ERROR -- invalid DSNMCom command Cause. DSNMCom is unable to recognize the command because the command line did not begin with the current COMMAND-CHAR character, and the command is not a valid DSNM command. Effect. The command is not executed. Recovery. Correct and reissue the command. DSNM error: error-text ON filename Cause. A DSNM error occurred during the file operation. Effect. See the description in the error-text portion of the message.
DSNMCom: The I Process Test Utility DSNM Parser Errors SECURITY-INFO not added to command buffer Cause. An SPI error occurred. Effect. The command is sent without the security token. Recovery. No recovery action required. no server open Cause. The CLOSE command was given when no server was open. Effect. The command is not executed. Recovery. No recovery action needed. DSNM Parser Errors The following errors may be generated by the DSNM parser, which interprets DSNM commands before they are executed.
DSNM Parser Errors DSNMCom: The I Process Test Utility Exceeded param space Cause. You entered too many parameters or an excessively long parameter. Effect. The command is not executed. Recovery. Simplify the command or break it into two or more commands, if necessary. Invalid option Cause. You specified an option that is not valid for any command. Effect. The command is not executed. Recovery. Correct and reissue the command. Invalid option for this command Cause.
DSNMCom: The I Process Test Utility DSNM Parser Errors Object type table error Cause. A consistency error was encountered in the parser object type table. Effect. Commands cannot be correctly interpreted. Recovery. Contact your Tandem representative. Be prepared to describe the problem in detail as recommended in “What to Prepare Before Contacting Your Tandem Support Representative” on page B-1. Param datatype table error Cause.
DSNM Parser Errors DSNMCom: The I Process Test Utility Unbalanced parens Cause. Your command includes parentheses that are incorrectly paired. Effect. The command is not executed. Recovery. Correct and reissue the command. Unexpected end Cause. The command did not include all required and expected information. Effect. The command is not executed. Recovery. Correct and reissue the command.
A DSNM Library Services Scope of This Appendix This appendix provides the following information (as applicable) for each define, literal, procedure, global variable, and structure template listed in Table A-1 below: • • • • • Description Syntax Parameter descriptions Considerations (additional information) Examples Table A-1.
Scope of This Appendix DSNM Library Services Table A-1.
Scope of This Appendix DSNM Library Services Table A-1.
Scope of This Appendix DSNM Library Services Table A-1.
DSNM Library Services _ADD^CI _ADD^CI _ADD^CI retrieves CI configuration information from the DSNM configuration file (DSNMCONF). It allocates the memory for and completes a predefined CI configuration structure with this information. It then returns the address of the completed structure. You must declare an extended pointer to a structure defined by _CI^DEF in your global definitions for each CI with which your subsystem communicates.
_ADD^CI DSNM Library Services Example < in global definitions > INT .EXT scp (_CI^DEF); INT .EXT snaxcdf (_SUBSYS^DEF); STRING .scpclass[0:ZDSN^MAX^CICLASS-1] := [“SCP “]; STRING .cdf[0:ZDSN^MAX^SUBSYS-1] := [“SNAXCDF “]; < within _STARTUP procedure > . . IF _ISNULL (@scp := _ADD^CI (scpclass)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; IF _ISNULL (@snaxcdf := _ADD^SUBSYS (cdf)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; . . < within _COMMAND^PROC procedure > . . CALL _OPEN^CI (scp, ... ); . .
DSNM Library Services _ADD^SUBSYS _ADD^SUBSYS _ADD^SUBSYS retrieves subsystem and object type configuration information from the DSNM configuration file (DSNMCONF). It allocates the memory for and completes a predefined subsystem configuration structure with this information. It then returns the address of the completed structure. You must declare an extended pointer to a subsystem configuration structure defined by _SUBSYS^DEF in your global definitions for each subsystem your I-process handles.
_ADD^SUBSYS DSNM Library Services Example < in global definitions > INT .EXT scp (_CI^DEF); INT .EXT snaxcdf (_SUBSYS^DEF); STRING .scpclass[0:ZDSN^MAX^CICLASS-1] := [“SCP “]; STRING .cdf[0:ZDSN^MAX^SUBSYS-1] := [“SNAXCDF “]; < within _STARTUP procedure > . . IF _ISNULL (@scp := _ADD^CI (scpclass)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; IF _ISNULL (@snaxcdf := _ADD^SUBSYS (cdf)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; . .
_ALLOFF DSNM Library Services _ALLOFF _ALLOFF is a Boolean define statement that is TRUE if every one-bit of bit-mask is off in int-exp. TRUE is nonzero, not necessarily -1. The _ALLOFF function is the same as the _OFF function. It is more descriptive to use _ALLOFF when testing more than one bit. _ALLOFF ( int-exp , bit-mask ) input int-exp INT:value is the INT expression being compared with bit-mask.
_ALLON DSNM Library Services _ALLON _ALLON is a Boolean define statement that is TRUE if every one-bit of bit-mask is on in int-exp. TRUE is nonzero, not necessarily -1. _ALLON ( int-exp , bit-mask ) input int-exp INT:value is the INT expression being compared with bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-exp to test.
DSNM Library Services _ALLON^TURNOFF _ALLON^TURNOFF If every one-bit of bit-mask is on in int-var, _ALLON^TURNOFF returns TRUE and turns off every one-bit of int-var that is on in bit-mask. TRUE is nonzero, not necessarily -1. _ALLON^TURNOFF ( int-var , bit-mask ) int-var input/output INT:ref is the variable compared with bit-mask. bit-mask input INT:value is an INT expression, the one-bits of which identify the bits in int-var to turn off.
_ANYOFF DSNM Library Services _ANYOFF _ANYOFF is a Boolean define statement that is TRUE if any one-bit of bit-mask is off in int-exp. TRUE is nonzero, not necessarily -1. _ANYOFF ( int-exp , bit-mask ) input int-exp INT:value is the INT expression compared with bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-exp to test.
_ANYON DSNM Library Services _ANYON _ANYON is a Boolean define statement that is TRUE if any one-bit of bit-mask is on in int-exp. TRUE is nonzero, not necessarily -1. The _ANYON function is the same as the _ON function. It is more descriptive to use _ANYON when testing more than one bit. _ANYON ( int-exp , bit-mask ) input int-exp INT:value is the INT expression compared with bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-exp to test.
_ANYON^TURNOFF DSNM Library Services _ANYON^TURNOFF If any one-bit of bit-mask is on in int-var, _ANYON^TURNOFF returns TRUE and turns off any one-bits in int-var that are on in bit-mask. TRUE is nonzero, not necessarily -1. _ANYON^TURNOFF ( int-var , bit-mask ) input/output int-var INT:ref is the variable compared with bit-mask. bit-mask input INT:value is an INT expression, the one-bits of which identify the bits in int-var to turn off.
_APPEND^OUTPUT DSNM Library Services _APPEND^OUTPUT _APPEND^OUTPUT appends text and other variable-length items to an output list member. The maximum allowed length of a character string (ZDSN-MAX-TEXT) is 75 characters. Text and other variable-length items can only be appended to the frame output list. error := _APPEND^OUTPUT ( output-list-member ,type ,[ header ] ,[ header-len ] ,[ body ] ,[ body-len ] ); returned value error INT is a ZDSN^ERR value indicating the outcome of the call.
_APPEND^OUTPUT DSNM Library Services input header STRING .EXT is the appended item's header. If header is terminated with a null, then header-len is not required. input header-len INT:value is the length, in bytes, of the appended item’s header. Required only if header does not terminate with a null byte. input body STRING .EXT is the item to be appended to the output list member. If body terminates with a null byte, body-len is not required. body should be appropriate to the value represented.
DSNM Library Services • _APPEND^OUTPUT A type ZDSN^VTY^COUNTERS structure is described by ZDSN^DDL^COUNTERS^DEF and contains the number of objects of the Z^OBJTYPE in each DSNM state. The relevant counters structure fields are: INT(32) Z^GREEN; INT(32) Z^UP = Z^GREEN; INT(32) Z^RED; INT(32) Z^DOWN = Z^RED; INT(32) Z^YELLOW; INT(32) Z^PENDING = Z^YELLOW; INT(32) Z^UNDEFINED; INT(32) Z^INERROR; For more information, see the description of the AGGREGATE command in Section 4, “DSNM Command Requirements.
_BITDEF DSNM Library Services _BITDEF _BITDEF defines a bit within a specified range of bits. A compile error is generated if int falls outside of the range min-bit to max-bit, inclusive. _BITDEF ( int [,max-bit ] [,min-bit ] ) input int the bit position to be defined within the range min-bit to max-bit, inclusive. input max-bit the leftmost bit position within the word that is now considered bit position 0. The default is %100000. input min-bit the rightmost bit position within the range.
_BITDEF DSNM Library Services The next example generates a compile error because it attempts to assign a value to a bit position outside of the designated range: LITERAL z = BITDEF (4, %40, %10); Bit position 4 is outside range %40 and %10 0 1 2 3 4 5 6 7 8 9 10 11 12 0 1 %40 2 13 14 3 4 15 %10 Range 402 Bit position 4 requires a rightmost bit position range delimiter equal to or greater than %2 (_BITDEF(14)).
_CANCEL^SEND^CI DSNM Library Services _CANCEL^SEND^CI _CANCEL^SEND^CI cancels an outstanding _SEND^CI operation. The thread cancels all outstanding _SEND^CI operations when the thread terminates. error := _CANCEL^SEND^CI ( [ tag ] ); returned value error INT is a file system error. File system errors are documented in the Guardian Procedure Errors and Messages Manual. input tag INT(32):value is the tag of an outstanding _SEND^CI operation.
DSNM Library Services _CANCEL^TIMEOUT _CANCEL^TIMEOUT _CANCEL^TIMEOUT cancels an outstanding timeout set by a call to _SET^TIMEOUT. The tag of the canceled operation is stored in the command context space and can be accessed with _LAST^TIMEOUT^TAG. error := _CANCEL^TIMEOUT ( [ tag ] ); error returned value INT is a ZDSN^ERR value indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions.
_CI^DEF DSNM Library Services _CI^DEF _CI^DEF is a template for a CI configuration structure, filled in by the _ADD^CI procedure. _CI^DEF You must declare an extended pointer to a _CI^DEF-defined CI configuration structure in globals for each CI with which your I process communicates. _ADD^CI must be called in your _STARTUP procedure for each CI class your with which your I process communicates. (_ADD^CI allocates the memory for, fills in, and returns the address of the CI configuration structure.
DSNM Library Services _CI^DEF Example < in global definitions > INT .EXT scp (_CI^DEF); INT .EXT snaxcdf (_SUBSYS^DEF); STRING .scpclass[0:ZDSN^MAX^CICLASS-1] := [“SCP ”]; STRING .cdf[0:ZDSN^MAX^SUBSYS-1] := [“SNAXCDF ”]; < within _STARTUP procedure > . . IF _ISNULL (@scp := _ADD^CI (scpclass)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; IF _ISNULL (@snaxcdf := _ADD^SUBSYS (cdf)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; . . < within _COMMAND^PROC procedure > . . CALL _OPEN^CI (scp, ... ); . .
_CI^FILENUM DSNM Library Services _CI^FILENUM _CI^FILENUM gives the type INT file number of the CI involved with the mostrecently completed communication. filenumber := _CI^FILENUM ( ciid ) output filenumber INT is the INT Guardian file number of the CI involved in the most-recently completed communication. input ciid is the CIID structure (declared with _CI^ID) identifying an open CI.
_CI^ID DSNM Library Services _CI^ID _CI^ID declares a structure (referred to as a “CIID” structure) in which _OPEN^CI stores information about an open CI. _CI^ID ( ciid ); user-provided identifier ciid is the name (a valid TAL identifier) given to the CIID structure with which an open CI can be accessed. The CIID structure plays a role in command-thread CI communication analogous to a file number in Tandem NonStop Kernel interprocess communications.
_CI^IDPOINTER DSNM Library Services _CI^IDPOINTER _CI^IDPOINTER_CI^IDPOINTER declares an extended pointer to a CIID structure. After the thread is dispatched by the frame with _EV^IODONE, _LAST^CI^ID is a type _CI^IDPOINTER pointer, which gives access to information about the CI causing the event. _CI^IDPOINTER ( ciid ); input ciid declares a pointer to a CIID structure (declared with _CI^ID).
_CI^LASTERROR DSNM Library Services _CI^LASTERROR _CI^LASTERROR is the type INT file-system error of the last CI operation. fserror := _CI^LASTERROR ( ciid ) output fserror INT is the file-system error of the last CI operation. input ciid is the CIID structure (declared with _CI^ID) identifying an open CI. Considerations If _CI^LASTERROR is not 0, the following actions occurred: • • Retriable errors were retried unsuccessfully.
_CI^REPLYADDRESS DSNM Library Services _CI^REPLYADDRESS _CI^REPLYADDRESS is the type INT(32) extended address of the reply buffer containing information read from a CI on completion of a _SEND^CI. @replyaddress := _CI^REPLYADDRESS ( ciid ) output replyaddress INT(32) is the extended address of the reply buffer. input ciid is the CIID structure (declared with _CI^ID) identifying an open CI.
DSNM Library Services _CI^REPLYLENGTH _CI^REPLYLENGTH _CI^REPLYLENGTH is the type INT length of the reply buffer containing information read from a CI on completion of a _SEND^CI. replylength := _CI^REPLYLENGTH ( ciid ) replylength output INT is the length of the reply buffer. ciid input is the CIID structure (declared with _CI^ID) identifying an open CI.
_CI^REPLYTAG DSNM Library Services _CI^REPLYTAG _CI^REPLYTAG is the type INT(32) tag associated with the last CI operation. replytag := _CI^REPLYTAG ( ciid ) output replytag INT(32) is the tag associated with the last CI operation. input ciid is the CIID structure (declared with _CI^ID) identifying an open CI.
DSNM Library Services _CLOSE^CI _CLOSE^CI _CLOSE^CI terminates a CI communication. In addition, _CLOSE^CI cancels all outstanding I/O operations. You must close a CI before its CIID structure (ciid) can be used in another _OPEN^CI operation. error := _CLOSE^CI ( ciid ); error returned value INT is a file-system error. File system errors are documented in the Guardian Procedure Errors and Messages Manual. ciid input is the CIID structure (declared with _CI^ID) identifying an open CI.
_COMMAND^CONTEXT^HEADER DSNM Library Services _COMMAND^CONTEXT^HEADER _COMMAND^CONTEXT^HEADER defines and reserves the fixed header portion of the command context space that is allocated to each thread when it is created and that persists until the thread terminates. This part of the command context space is reserved for the specific uses described in Section 3, “I Process Development Process.
DSNM Library Services _COMMAND^PROC _COMMAND^PROC _COMMAND^PROC is the name of the first command thread procedure to be dispatched by the frame. _THREAD^PROC (_COMMAND^PROC); Considerations The frame invokes the command thread as _COMMAND^PROC the first time it dispatches an instance of the thread. It is required to have one thread defined with this name in the I process.
_COMMAND^TERMINATION^PROC DSNM Library Services _COMMAND^TERMINATION^PROC _COMMAND^TERMINATION^PROC is the name of the thread termination procedure declared with _THREAD^TERMINATION^PROC. _THREAD^TERMINATION^PROC ( _COMMAND^TERMINATION^PROC); Example Use _COMMAND^TERMINATION^PROC in the following construction: _THREAD^TERMINATION^PROC (_COMMAND^TERMINATION^PROC); BEGIN . < procedure body > .
DSNM Library Services _COMPILED^IN^TESTMODE _COMPILED^IN^TESTMODE _COMPILED^IN^TESTMODE is a literal with a value of 1, if a source file is compiled with the SETTOG 1 compiler directive; otherwise, _COMPILED^IN^TESTMODE is 0. Use _COMPILED^IN^TESTMODE to set the value of the testmode parameter in your _STARTUP^MODE procedure. _COMPILED^IN^TESTMODE Example INT PROC _STARTUP^MODE (component, testmode, accept^startup^component) EXTENSIBLE; STRING .EXT component; INT .
_DEALLOCATE^LIST DSNM Library Services _DEALLOCATE^LIST _DEALLOCATE^LIST deletes all members of a list. Memory for the list members is deallocated immediately. CALL _DEALLOCATE^LIST ( list ); input list is the name of a _LIST. Example CALL _DEALLOCATE^LIST (cx.xc.
_DELETE^LM DSNM Library Services _DELETE^LM _DELETE^LM deletes a member of a list, immediately deallocates its memory, and sets the list-member pointer to null. error := _DELETE^LM ( list ,@list-member ); error returned value INT is a ZDSN^ERR value, indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions. list input is the name of a _LIST. list-member input/output INT .EXT is a pointer to the member to be deleted from list.
_DEPOSIT DSNM Library Services _DEPOSIT _DEPOSIT sets selected bits in the first parameter equal to the same bits in the second parameter. _DEPOSIT ( int-var ,int-exp ,bit-mask ); input/output int-var INT:ref is INT variable, the selected bits of which are set equal to the same bits in int-exp. input int-exp INT:value is an INT expression, the selected bits to which int-var bits are set equal.
DSNM Library Services _DISPATCH^THREAD _DISPATCH^THREAD _DISPATCH^THREAD returns to the frame and causes a new dispatch. It is effective only in a thread procedure, not in an auxiliary procedure or a subprocedure. _DISPATCH^THREAD saves no information about the procedure from which it was invoked. This function cannot detect any failures and performs an unconditional RETURN operation. _DISPATCH^THREAD ( [ @procname ] ,[ state ] ,[ event ] ); procname input is the dispatched thread procedure.
_DSNMCONF^PARAMS DSNM Library Services _DSNMCONF^PARAMS _DSNMCONF^PARAMS is a global structure, defined and stored in the I process globals. The frame retrieves these parameters as part of its startup function. STRUCT _DSNMCONF^PARAMS (ZDSN^DDL^DSNMCONF^PARAMS^DEF); Considerations The contents of the _DSNMCONF^PARAMS structure is as follows: DEFINITION ZDSN-DDL-DSNMCONF-PARAMS. 02 Z-DSNM-MANAGER-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-DSNM-MANAGER TYPE ZDSN-DDL-MANAGER. 02 Z-SWAPVOL-OCCURS TYPE ZSPI-DDL-UINT.
DSNM Library Services _EMPTY^LIST _EMPTY^LIST _EMPTY^LIST is a Boolean define statement that is TRUE if list has no members. TRUE is nonzero, not necessarily -1. _EMPTY^LIST ( list ) list input is the name of a _LIST . Example The following example tests if list is empty: _LIST (list); IF _EMPTY^LIST (list) THEN ...
_EMS^EVENT^CRITICAL DSNM Library Services _EMS^EVENT^CRITICAL _EMS^EVENT^CRITICAL is a value used in the _REPORT^INTERNAL^ERROR and _REPORT^STARTUP^ERROR procedures, indicating that the event being logged to EMS is critical but not fatal. _EMS^EVENT^CRITICAL _EMS^EVENT^FATAL _EMS^EVENT^FATAL is a value used in the _REPORT^INTERNAL^ERROR and _REPORT^STARTUP^ERROR procedures, indicating that the event being logged to EMS is fatal.
DSNM Library Services _END^THREAD^PROC _END^THREAD^PROC _END^THREAD^PROC ends a thread procedure definition. Any procedure that can be dispatched as part of a thread must be declared with _THREAD^PROC and _END^THREAD^PROC. _END^THREAD^PROC issues RETURN _RC^WAIT.
_END^THREAD^TERMINATION^PROC DSNM Library Services _END^THREAD^TERMINATION^PROC _END^THREAD^TERMINATION^PROC ends a thread termination procedure definition and issues RETURN _RC^NULL. The thread termination procedure declared with _THREAD^TERMINATION^PROC must end with _END^THREAD^TERMINATION^PROC.
DSNM Library Services _EV^TIMEOUT _EV^CANCEL _EV^CANCEL is generated by the frame when it receives a command cancellation request. The command thread can be dispatched with _EV^CANCEL after any return to the frame; the operation should be terminated immediately. _EV^CANCEL _EV^CANCEL should be handled like an error: you must perform clean-up operations, such as freeing resources, returning the CI to a reasonable state, and so on.
_EXTRACT DSNM Library Services _EXTRACT _EXTRACT returns the value of those bits of bit-mask that are on in int-exp. _EXTRACT performs a function similar to the TAL bit-extraction operation, except the extracted bits need not be contiguous, nor are they shifted to the right. _EXTRACT ( int-exp , bit-mask ); input int-exp INT:value is an INT expression from which bits are extracted, according to the one-bits in bit-mask.
_FIRST^LM DSNM Library Services _FIRST^LM _FIRST^LM returns the address of the first member of a list. _NULL is returned if the list is empty. @first-list-member := _FIRST^LM ( list ); returned value first-list-member INT .EXT is the address of the first member of list. input list is the name of a _LIST. Example _LIST (outlist); INT .
FOBJECT DSNM Library Services FOBJECT Every subsystem object processed by DSNM is defined by the contents of a ZDSN^DDL^FOBJECT^DEF structure, known as a “formatted object.” The _INPUT^LM^HEADER and _OUTPUT^LM^HEADER defines assign the name FOBJ to the formatted object structure portions of input and output list members. It is important that every object processed by the command thread be represented in an FOBJECT structure, properly initialized with the _FOBJECT^INIT procedure.
DSNM Library Services FOBJECT ! Create output list member IF _ISNULL (@cx.outobj := _PUT^LM (out.OBJECTLIST,, $LEN (cx.outobj))) THEN ... < out of available memory > ; . . IF (error := _FOBJECT^INIT (cx.outobj.FOBJ,, cx.inobj.FOBJ)) THEN ... < error exit > ; cx.outobj.FOBJ.Z^RESULT := < status of subordinate >; cx.outobj.FOBJ.Z^OBJTYPE ':=' < type of subordinate >; cx.outobj.FOBJ.Z^OBJNAME ':=' < name of subordinate >; _RELEASE^OUTPUT (cx.outobj); . .
_FOBJECT^INIT DSNM Library Services _FOBJECT^INIT _FOBJECT^INIT initializes a new FOBJECT structure and determines required fields from its source FOBJECT structure. _FOBJECT^INIT does not allocate memory; memory for the new formatted object must be allocated previously. error := _FOBJECT^INIT ( new-fobject ,[ same-fobject ] ,[ parent-fobject ]); returned value error INT is a ZDSN^ERR value, indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions.
DSNM Library Services • _FOBJECT^INIT Use the parent-fobject argument if the new FOBJECT structure is to define a different object from any previously initialized FOBJECT structure. Specify the new object’s parent in the name hierarchy as described above as the parentfobject. The new object is different if it differs in any of subsystem, object type, name, or manager from its name parent (the name from which the new object was derived by expanding a “*” or through the subsystem hierarchy).
_FOBJECT^INIT DSNM Library Services Example In the following example, each input object and its hierarchical subordinates appear in the output for a STATUS command: STRUCT input^lm^def (*); BEGIN _INPUT^LM^HEADER; ... END; STRUCT output^lm^def (*); BEGIN _OUTPUT^LM^HEADER; ... END; STRUCT command^context^def (*); BEGIN _COMMAND^CONTEXT^HEADER; INT .EXT inobj (input^lm^def); INT .EXT outobj (output^lm^def); END; !Thread proc locals! INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .
DSNM Library Services _FOBJECT^INIT ! Use state variables to return to this point after the ! _EV^IODONE event occurs cx.outobj.FOBJ.Z^RESULT := < status of input object >; ! Since this completes the current output object, release it _RELEASE^OUTPUT (cx.outobj); ! Enter subordinates and their status into output list ! (Assuming one CI communication returns all subordinates) WHILE < more subordinate objects > DO BEGIN IF _ISNULL (@cx.outobj := _PUT^LM (out.OBJECTLIST,, $LEN (cx.outobj))) THEN ...
_GET^LM DSNM Library Services _GET^LM _GET^LM removes the current first member (the earliest member put on the list) from a list and returns its address. If the list is empty, _GET^LM returns _NULL. @list-member := _GET^LM ( list ,[ length ] ); returned value list-member INT .EXT is the address of the removed member. input list is the name of a _LIST. output length INT:ref returns the length of the removed member, in bytes.
_GET^PARAM DSNM Library Services _GET^PARAM _GET^PARAM retrieves one instance of a DSNM configuration parameter that is not part of the standard set stored in the _DSNMCONF^PARAMS structure. error := _GET^PARAM ( paramscope , paramtype ,[ subsys ] ,[ class ] ,[ component ] , paramname , paramvalue:maxlen ,[ len ] ,[ error-filename ] ); returned value error INT is a ZDSN^ERR or Guardian error. See Appendix B, “DSNM Error Codes,” for ZDSN^ERR error code definitions.
_GET^PARAM DSNM Library Services input paramtype INT indicates how restrictive the search criteria is: _COMPONENT^PARAM Component parameters are instances of a parameter, specific to this component and class. _CLASS^PARAM Class parameters are instances of a parameter, specific to this class. If component is blank, it is specific to the class as a whole. _GENERAL^PARAM General parameters are any instance of this parameter.
DSNM Library Services _GET^PARAM input maxlen INT is the maximum length returned in paramvalue, in bytes. len output INT is the actual length of the value returned in paramvalue, in bytes. If len < maxlen, the remainder of paramvalue is blank-filled. error-filename output STRING .EXT ! ZDSN^DDL^OBJNAME^DEF ! is the name of the configuration file associated with the returned error value.
_GET^PROCESS^PARAM DSNM Library Services _GET^PROCESS^PARAM _GET^PROCESS^PARAM retrieves process startup parameters not part of the standard set stored in the _PROCESS^PARAMS structure. error := _GET^PROCESS^PARAM ( paramname , paramvalue:maxlen ,[ len ] ); returned value error INT is a ZDSN^ERR or Guardian error. See Appendix B, “DSNM Error Codes,” for ZDSN^ERR error code definitions. Refer to the Guardian Procedure Errors and Messages Manual for Guardian error descriptions. input paramname STRING .
DSNM Library Services _INITIALIZE^LIST _INITIALIZE^LIST _INITIALIZE^LIST sets a list structure to nulls. (Lists defined in the thread context do not have to be initialized with _INITIALIZE^LIST.) _INITIALIZE^LIST sets the list header structure to nulls. Do not use it to deallocate members of a list (see the _DEALLOCATE^LIST description). CALL _INITIALIZE^LIST ( list ); list input is the name of a _LIST.
_INPUT DSNM Library Services _INPUT _INPUT is the name assigned to the _INPUT^DEF structure template within the command context area (where the frame places the command components). The _COMMAND^CONTEXT^HEADER define assigns the _INPUT name. Example The following example of a local data definition gives a thread procedure access to the input area: INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .EXT in (_INPUT^DEF) := @cx.
DSNM Library Services _INPUT^DEF _INPUT^DEF _INPUT^DEF is a structure template into which the frame places the action and command modifiers to be passed to the thread. STRUCT _INPUT^DEF (*); BEGIN _LIST (OBJECTLIST); INT action; STRUCT mod (zdsn^mod^def); END; Example The following example of a local data definition gives a thread procedure access to the input area: INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .EXT in (_INPUT^DEF) := @cx.
_INPUT^LM^HEADER DSNM Library Services _INPUT^LM^HEADER _INPUT^LM^HEADER describes the first part of the user-defined input list member structure. It is required as part of the input list member definition. _INPUT^LM^HEADER generates a formatted object structure (ZDSN^DDL^FOBJECT^DEF); it identifies this object structure as FOBJ and identifies other fields for the frame.
DSNM Library Services _INPUT^LM^HEADER Example The following is an example of an input list member structure declaration: STRUCT input^list^member^def (*); BEGIN _INPUT^LM^HEADER; < user-definitions > ... END; See the _FOBJECT^INIT description for another _INPUT^LM^HEADER example.
_ISNULL DSNM Library Services _ISNULL _ISNULL is a Boolean define statement that is TRUE if address is a null extended memory pointer. TRUE is nonzero, not necessarily -1. Always use either _ISNULL or _NOTNULL to test a pointer rather than comparing it to the library literal _NULL. (There are multiple internal values that are accepted as equivalent to _NULL.) _ISNULL ( address ) input address INT(32):value is the extended address being tested.
_JOIN^LIST DSNM Library Services _JOIN^LIST _JOIN^LIST appends all members of a source list to a destination list. Data is not moved in memory; the source list is empty afterwards. error := _JOIN^LIST ( dest-list ,source-list ); error returned value INT is a ZDSN^ERR value indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions. dest-list input/output is the name of the destination _LIST to which the members of source-list are appended.
KDSNDEFS DSNM Library Services KDSNDEFS KDSNDEFS is the source file for all I process development definitions and declarations.
DSNM Library Services _LAST^CI^ID _LAST^CI^ID _LAST^CI^ID is a command context field that points to the CIID structure from the last _EV^IODONE event. Its type is _CI^IDPOINTER. command-context._LAST^CI^ID Example In the following example, mgr is set to point to the CIID involved in the most-recently completed CI communication: _CI^IDPOINTER (mgr); int .ext cx(command^context^def) = _THREAD^CONTEXT^ADDRESS; IF _ON (_LAST^EVENTS, _EV^IODONE) THEN BEGIN @mgr := cx.
_LAST^EVENTS DSNM Library Services _LAST^EVENTS _LAST^EVENTS is set each time a command thread is dispatched to contain the event(s) that caused the dispatch. Each bit represents a different event. _LAST^EVENTS Considerations • • • • _LAST^EVENTS is an INT global variable that can be tested and altered; _REAL^LAST^EVENTS, which is also set to the current event(s) at each dispatch, can only be tested.
DSNM Library Services _LAST^LM _LAST^LM _LAST^LM returns the address of the last (most recent) member of a list. If a list is empty, _NULL is returned. @last-list-member := _LAST^LM ( list ); last-list-member returned value INT .EXT is the address of the last member of list. list input is the name of a _LIST. Example INT .EXT cx(command^context^def) := _THREAD^CONTEXT^ADDRESS; _LISTPOINTER (outlist) := @cx.OUTPUT.OBJECTLIST; INT .
_LAST^TIMEOUT^TAG DSNM Library Services _LAST^TIMEOUT^TAG _LAST^TIMEOUT^TAG is a command context field, set to the INT(32) timeout tag associated with the _SET^TIMEOUT request, and completed by the last _EV^TIMEOUT event. It is convenient to use the address of a list member as a timeout tag to hold information about the purpose of the timeout, as illustrated in the example. command-context._LAST^TIMEOUT^TAG Example STRUCT time^info^def (*); BEGIN . . END; INT .
_LIST DSNM Library Services _LIST _LIST declares a list structure. _LIST ( list ); user-provided identifier list is the name (a valid TAL identifier) of the structure that _LIST declares. Considerations • The data structure known as a “list” is the basis for the I process programdevelopment software memory-management facility. A list consists of the structure declared with _LIST and the list members. • • • The list structure holds control information, used by the list library procedures.
_LISTPOINTER DSNM Library Services _LISTPOINTER _LISTPOINTER declares an extended pointer to a _LIST structure. Once a list pointer is initialized with a list address, it can be used anywhere _LIST is used. _LISTPOINTER ( list ); user-provided identifier list is the name (a valid TAL identifier) of the list pointer. Example INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; _LISTPOINTER (outlist) := @cx._OUTPUT.OBJECTLIST; INT .EXT out^lm (output^lm^def); . . .
DSNM Library Services _MEMBERSOF^LIST _MEMBERSOF^LIST _MEMBERSOF^LIST is the type INT(32) number of members currently in a list. _MEMBERSOF^LIST ( list ) list input is the name of a _LIST.
_MOVE^LIST DSNM Library Services _MOVE^LIST _MOVE^LIST moves all members of a source list to the destination list. After the operation, the source list is empty. CALL _MOVE^LIST ( dest-list, source-list ) input/output dest-list is the name of the destination _LIST to which the members of source-list are moved. input/output list is the name of the source _LIST whose members are moved to the dest-list. Considerations dest-list should not have any members prior to the operation.
DSNM Library Services _NOTNULL _NOTNULL _NOTNULL is a Boolean define statement that is TRUE if address is a nonnull extended memory pointer. TRUE is nonzero, not necessarily -1. Always use either _NOTNULL or _ISNULL to test a pointer rather than comparing it to the library literal _NULL. (There are multiple internal values that are accepted as equivalent to _NULL.) _NOTNULL ( address ) address input INT(32) is the tested extended address.
_NULL DSNM Library Services _NULL _NULL is an INT(32) literal, defining a null value for an extended memory pointer. Always use _NULL for a null pointer value. Never test a pointer for null by comparing it to _NULL; always use _ISNULL or _NOTNULL for such tests. The I process program-development libraries use a range of null values. _NULL is guaranteed to be in the range, but is not the only possible null pointer value. A pointer set to _NULL causes an address trap, if used, to access memory.
DSNM Library Services _NULL^LIST _NULL^LIST _NULL ^LIST initializes a list structure. It is useful to initialize a _LIST declared in an uninitialized memory area. CALL _NULL^LIST( list ); list input/output is the name of a _LIST. Considerations _NULL^LIST does not deallocate an existing list. Use _DEALLOCATE^LIST to remove and deallocate all existing list members. list must not have any members prior to the operation.
OBJECTLIST DSNM Library Services OBJECTLIST OBJECTLIST is the name assigned to the input and output object lists by the _COMMAND^CONTEXT^HEADER define. Example The following example gets a member off the input list and creates a member on the output list: STRUCT input^lm^def (*); BEGIN _INPUT^LM^HEADER; ... END; STRUCT output^lm^def (*); BEGIN _OUTPUT^LM^HEADER; ... END; STRUCT command^context^def (*); BEGIN _COMMAND^CONTEXT^HEADER; INT .EXT inobj (input^lm^def); INT .
DSNM Library Services _OFF _OFF _OFF is a Boolean define statement that is TRUE if any one-bit of bit-mask is off in int-exp. TRUE is nonzero, not necessarily -1. The _OFF function is the same as the _ALLOFF function. It is more descriptive to use _ALLOFF when testing more than one bit. _OFF ( int-exp , bit-mask ) int-exp input INT:value is the INT expression compared with bit-mask. bit-mask input INT:value is an INT expression, the one-bits of which identify the bits in int-exp to test.
_ON DSNM Library Services _ON _ON is a Boolean define statement that is TRUE if any one-bit of bit-mask is on in int-exp. TRUE is nonzero, not necessarily -1. The _ON function is the same as the _ANYON function. It is more descriptive to use _ANYON when testing more than one bit. _ON ( int-exp , bit-mask ) input int-exp INT:value is the variable compared with bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-exp to test.
DSNM Library Services _OPEN^CI _OPEN^CI _OPEN^CI opens a CI for communication. error := _OPEN^CI ( ci-config ,ciid ,[ processname ] ,[ nowait-depth ]) error returned value INT If > 0, is the file system error returned from the FILE_OPEN_ procedure. File system errors are described in the Guardian Procedure Errors and Messages Manual. If < 0, is a ZDSN error. See Appendix B, “DSNM Error Codes,” for ZDSN error code definitions. ci-config input is the extended pointer (declared in globals).
_OPEN^CI • • • DSNM Library Services To communicate with a server CI, you must allocate a message buffer large enough to hold the larger of the message and its response. This buffer must be in the command context space or in an allocated list member. It cannot be in globals or procedure locals. If more than one operation is to be outstanding (whether on the same or on separate CIs), you should also supply an INT(32) tag for the operation, usually a pointer to some identifying data.
DSNM Library Services _OPEN^CI INT .EXT cx (context^def) = _THREAD^CONTEXT^ADDRESS; INT error, cmd^len; LITERAL max^cmd = ..., max^reply = ...; IF (error := _OPEN^CI (scp, cx.current^ci, cx.input^lm.FOBJ.Z^MANAGER); THEN ... < open error > ; . .
_OUTPUT DSNM Library Services _OUTPUT _OUTPUT is the name assigned to the _OUTPUT^DEF structure template within the command context area where the frame declares the output object list (OBJECTLIST). _OUTPUT is assigned by _COMMAND^CONTEXT^HEADER. Example The following example of a local data definition gives a thread procedure access to the output area: INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .EXT out (_OUTPUT^DEF) := @cx.
DSNM Library Services _OUTPUT^DEF _OUTPUT^DEF _OUTPUT^DEF is a structure template where the frame declares the output object list (OBJECTLIST). STRUCT _OUTPUT^DEF (*); BEGIN _LIST (OBJECTLIST); END; Example The following example of a local data definition gives a thread procedure access to the output area: INT .EXT cx (command^context^def) = _THREAD^CONTEXT^ADDRESS; INT .EXT out (_OUTPUT^DEF) := @cx._OUTPUT; See the _FOBJECT^INIT description for another _OUTPUT^DEF example.
_OUTPUT^LM^HEADER DSNM Library Services _OUTPUT^LM^HEADER _OUTPUT^LM^HEADER describes the first part of the user-defined output list member structure. It is required as part of the output list member definition. _OUTPUT^LM^HEADER generates a formatted object structure (ZDSN^DDL^FOBJECT^DEF); it identifies this object structure as FOBJECT and identifies other fields for the frame.
_POP^LM DSNM Library Services _POP^LM _POP^LM removes the current last member (most recently added) from a list and returns its address. If a list is empty, _POP^LM returns _NULL. @list-member := _POP^LM ( list ,[ length ] ); list-member returned value INT .EXT is the address of the removed member. list input is the name of a _LIST. length output INT:ref returns the length of the removed member, in bytes.
_POP^THREAD^PROCSTATE DSNM Library Services _POP^THREAD^PROCSTATE _POP^THREAD^PROCSTATE restores the values of the thread procedure and thread state saved with the most recent _PUSH^THREAD^PROCSTATE. error := _POP^THREAD^PROCSTATE ; returned value error INT is a ZDSN^ERR value indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions. Example See the example for _PUSH^THREAD^PROCSTATE.
DSNM Library Services _PREDECESSOR^LM _PREDECESSOR^LM _PREDECESSOR^LM returns the address of the list member placed on the list immediately before the current list member was added. @prev-list-member := _PREDECESSOR^LM ( list ,list-member ); prev-list-member returned value INT .EXT is the address of the predecessor of the current list member. input list is the name of a _LIST. list-member input INT .EXT is a pointer to a current member of list.
_PREDECESSOR^LM DSNM Library Services Example The following example sets two pointers, one to the last member of list, and another to the next-to-last member: _LIST (list); INT .EXT lm (list^member^def); !extended pointer to list !member structure INT .
DSNM Library Services _PRIVATE^THREAD^EVENT _PRIVATE^THREAD^EVENT _PRIVATE^THREAD^EVENT produces an INT constant with a single one-bit, suitable for labeling an event to look different from any frame-generated event. _PRIVATE^THREAD^EVENT ( num ); num is a number in the range 0 through 7. Considerations • • Currently, the thread can declare eight events guaranteed to be different from all frame-generated events. Thread procedures must call _SIGNAL^EVENT to generate private events.
_PROCESS^PARAMS DSNM Library Services _PROCESS^PARAMS _PROCESS^PARAMS is a global structure defined in the I process globals in which the frame stores standard process parameters it retrieves as part of its startup function. STRUCT _PROCESS^PARAMS (ZDSN^DDL^PROCESS^PARAMS^DEF); Considerations The contents of the _PROCESS^PARAMS structure is as follows: DEFINITION ZDSN-DDL-PROCESS-PARAMS. 02 Z-CLASS-OCCURS TYPE ZSPI-DDL-UINT. 02 Z-CLASS TYPE ZDSN-DDL-CLASS. 02 Z-COMPONENT-OCCURS TYPE ZSPI-DDL-UINT.
DSNM Library Services _PUSH^LM _PUSH^LM _PUSH^LM allocates memory for a new last member of a list and returns its address. _NULL is returned if no memory is available for a new list member. @list-member := _PUSH^LM ( list ,[ length ] ,initlength ,[ initdata ] ); list-member returned value INT .EXT is the address of the new member. list input is the name of a _LIST. length input INT:value is the length of the new member, in bytes.
_PUSH^LM DSNM Library Services Example The following example allocates space for a new list member initialized to binary 0s: _LIST (list); INT .
DSNM Library Services _PUSH^THREAD^PROCSTATE _PUSH^THREAD^PROCSTATE _PUSH^THREAD^PROCSTATE saves the current thread procedure and thread state, and optionally sets new values for the current thread procedure and thread state. error := _PUSH^THREAD^PROCSTATE ( [ @procname ] ,[ state ] ); error returned value INT is a ZDSN^ERR value, indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions.
_PUSH^THREAD^PROCSTATE DSNM Library Services PROC^Y checks for event EV^STARTUP, resets the current thread procedure and thread state to the previously saved values of PROC^X and STATE^A, and returns to the frame to dispatch PROC^X in STATE^A. _THREAD^PROC (PROC^X); BEGIN . . CASE _THREAD^STATE OF BEGIN _ST^INITIAL --> _THREAD^STATE := STATE^A; IF (error := _PUSH^THREAD^PROCSTATE(@PROC^Y,STATE^B)) THEN ... < error > ; CALL _SIGNAL^EVENT (_EV^STARTUP); RETURN _RC^WAIT; STATE^A --> . .
_PUT^LM DSNM Library Services _PUT^LM _PUT^LM allocates memory for a new last member of a list and returns its address. _NULL is returned if no memory is available for a new list member. @list-member := _PUT^LM ( list ,[ length ] ,initlength ,[ initdata ] ); list-member returned value INT .EXT is the address of the new member. list input is the name of a _LIST. length input INT:value is the length of the new member, in bytes.
_PUT^LM DSNM Library Services Example In the following example, the INIT^LM^VALUES structure is set to initializing values for each worklist member; then a list member is allocated and initialized to INIT^LM^VALUES: STRUCT .init^lm^values (lm^def); _LIST (worklist); INT .EXT lm (lm^def); IF _ISNULL(@lm :=_PUT^LM (worklist,,$LEN(lm),init^lm^values)) THEN ... ; See the _FOBJECT^INIT description for another _PUT^LM example.
DSNM Library Services _RC^STOP _RC^ABORT The thread returns _RC^ABORT to the frame when a command abnormally terminates. RETURN _RC^ABORT ( error ); error INT is a ZDSN^ERR value, indicating the reason for the abnormal command termination. See Appendix B, “DSNM Error Codes,” for error code definitions. _RC^NULL _RC^NULL is a special return code that is not equal to any valid thread return code; it must be returned to the frame in _COMMAND^TERMINATION^PROC.
_RC^TYPE DSNM Library Services _RC^TYPE _RC^TYPE declares function procedures that can be called by a thread procedure (but are not themselves thread procedures) and that return a frame return code value. _RC^TYPE also declares variables to hold the frame return code (_RC^) values such as values returned by _RC^TYPE function procedures. _RC^TYPE PROC procname ; _RC^TYPE var1, [ var2 [,...
DSNM Library Services _REAL^LAST^EVENTS _REAL^LAST^EVENTS _REAL^LAST^EVENTS is set each time the command thread is dispatched to contain the event(s) that caused the current dispatch. Each bit represents a different event. _REAL^LAST^EVENTS _REAL^LAST^EVENTS is a define that returns a value and as such, can only be tested; it cannot be altered. _LAST^EVENTS, which is also set to the current event(s) at each dispatch, is a global variable that can be tested and altered.
_RELEASE^OUTPUT DSNM Library Services _RELEASE^OUTPUT _RELEASE^OUTPUT releases a member of the output list to the frame. Once released, the output list member can be removed by the frame at the next frame return. Each output list member should be released as soon as it is completely completed. _RELEASE^OUTPUT ( output-list-member ); output-list-member input INT .EXT is the output list member released to the frame.
_REPORT^INTERNAL^ERROR DSNM Library Services _REPORT^INTERNAL^ERROR _REPORT^INTERNAL^ERROR logs internal errors to the $0 EMS collector. _REPORT^INTERNAL^ERROR ([ ,[ ,[ ,[ ,[ ,[ internalcode ] severity ] I1 ] I2 ] I3 ] I4 ] ); input internalcode INT:value is an internal code that you assign strictly for your own use.
_REPORT^STARTUP^ERROR DSNM Library Services _REPORT^STARTUP^ERROR _REPORT^STARTUP^ERROR reports fatal startup errors to the $0 EMS collector, resulting from _STARTUP procedure startup parameter or configuration errors. _REPORT^STARTUP^ERROR ([ internalcode ] ,[ severity ] ,[ text ] ); input internalcode INT:value is an internal code that you can assign strictly for your own use.
DSNM Library Services _REPORT^STARTUP^ERROR Example INT PROC _STARTUP (cxl, inputl) EXTENSIBLE; INT .cxl, .
_RESTORE^THREAD^AND^DISPATCH DSNM Library Services _RESTORE^THREAD^AND^DISPATCH _RESTORE^THREAD^AND^DISPATCH restores the thread procedure and state last pushed and returns to the frame for immediate dispatch with the specified event. _RESTORE^THREAD^AND^DISPATCH ( [ event ] ); input event INT:value is an INT expression that designates the event(s) with which the restored procedure is to be dispatched. The default is _EV^CONTINUE.
DSNM Library Services _SAVE^THREAD^AND^DISPATCH _SAVE^THREAD^AND^DISPATCH _SAVE^THREAD^AND^DISPATCH saves the current thread procedure and state, optionally sets new current thread procedure and state values, and returns to the frame for immediate dispatch. _SAVE^THREAD^AND^DISPATCH ( [ @procname ] ,[ state ] ,[ event ] ); procname input is the dispatched thread procedure. This procedure becomes the new current thread procedure. The default is to redispatch the existing current thread procedure.
_SEND^CI DSNM Library Services _SEND^CI _SEND^CI initiates sending a message to a server CI. After initiating _SEND^CI, the thread must eventually return to the frame to wait for its completion with _RC^WAIT. error := _SEND^CI ( ciid ,buffer ,write-count ,reply-count ,[ context-boolean ] ,[ tag ] ,[ timeout ] ); returned value error INT If > 0, is a file system error. File system errors are described in the Guardian Procedure Errors and Messages Manual. If < 0, is a ZDSN error.
_SEND^CI DSNM Library Services input context-boolean INT:value indicates whether the send is context-free, meaning it does not depend on any previous communication with this ciid. Specifically: • • If context-boolean is 0 (FALSE), the send is context-free, which means it may be sent to a new instance of the same CI if an error occurs.
_SEND^CI DSNM Library Services Example In the following example, the command thread initiates a _SEND^CI request and returns to the frame to wait for an I/O completion event: < within user globals area > STRUCT context^def (*); BEGIN ! Command thread context definition _COMMAND^CONTEXT^HEADER; INT .EXT input^lm (input^lm^def); ! Current input list ! member INT .
DSNM Library Services _SET^THREAD^PROC _SET^THREAD^PROC _SET^THREAD^PROC sets the current thread procedure to be called by the frame at the next thread dispatch. _SET^THREAD^PROC ( @procname ); procname input is the name of the thread procedure called by the frame at the next thread dispatch. Considerations • • Setting the current thread procedure is a high-level state change.
_SET^TIMEOUT DSNM Library Services _SET^TIMEOUT _SET^TIMEOUT allows the command thread to delay for a time interval by arranging for a future timeout event. CALL _SET^TIMEOUT ( time-interval ,[ tag ] ); input time-interval INT(32):value specifies the timeout period, in .01-second units. This value must be greater than 0. input tag INT(32):value is an identifier associated with the timer, which is placed into command context.
DSNM Library Services _SIGNAL^EVENT _SIGNAL^EVENT _SIGNAL^EVENT generates private events or simulates frame events. CALL _SIGNAL^EVENT ( event(s) ); event(s) input INT:value is an INT expression, the one-bits of which designate the event(s) to be generated. Considerations • • When the thread generates its own event(s) with _SIGNAL^EVENT, it is redispatched immediately when it returns _RC^WAIT to the frame. You may simulate any frame event by signaling it with _SIGNAL^EVENT.
_STARTUP DSNM Library Services _STARTUP _STARTUP is a user-provided initialization procedure called by the frame. It supplies the lengths of the user context area and input list members, and retrieves and places subsystem and CI configuration parameters into predefined structures for use by the frame. You must call _ADD^SUBSYS in your _STARTUP procedure for each subsystem your I process handles, as well as _ADD^CI for each CI class with which your I process communicates.
DSNM Library Services _STARTUP IF _ISNULL (@scp := _ADD^CI (scpclass)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; IF _ISNULL (@snaxcdf := _ADD^SUBSYS (cdf)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; RETURN ZDSN^ERR^NOERR; END; Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide— 109759 A-115
_STARTUP^MODE DSNM Library Services _STARTUP^MODE _STARTUP^MODE is a user-provided procedure called by the frame when it begins startup processing. _STARTUP^MODE retrieves the component name of the subsystem(s) being handled by the I process and determines if the I process is running in test mode and whether to use the COMPONENT process parameter value (if one appears in the startup message).
DSNM Library Services subject _STARTUP^MODE output STRING .EXT identifies the NULL-terminated value used in the EMS event messages. It can be the I process name. Example INT PROC _STARTUP^MODE ( component, testmode, accept^startup^component, subject ) EXTENSIBLE; STRING .EXT component; INT .EXT testmode; INT .EXT accept^startup^component; STRING .
_ST^INITIAL DSNM Library Services _ST^INITIAL When the frame creates a thread, it sets the thread state to _ST^INITIAL. The thread state value is stored in an INT context variable, accessible with the _THREAD^STATE define. See _ST^MIN^THREAD^STATE for information on defining your thread states. _ST^INITIAL Example The following example tests the current state of the thread: CASE _THREAD^STATE OF BEGIN _ST^INITIAL -> ... OTHERWISE -> ... END; . . .
DSNM Library Services _ST^MIN^THREAD^STATE _ST^MIN^THREAD^STATE _ST^MIN^THREAD^STATE is the minimum value of a user-defined thread state. _ST^MIN^THREAD^STATE Considerations • • • Thread states are normally declared as literals. Values less than _ST^MIN^THREAD^STATE are reserved for use by the frame. _THREAD^STATE contains the current thread state.
_SUBSYS^DEF DSNM Library Services _SUBSYS^DEF _SUBSYS^DEF is a template for a subsystem configuration structure, filled by the _ADD^SUBSYS procedure with subsystem and object-type configuration data. Declare an extended pointer to a _SUBSYS^DEF-defined subsystem configuration structure in globals for each subsystem your I process handles. _ADD^SUBSYS must be called in your _STARTUP procedure for each subsystem your I process handles.
DSNM Library Services _SUBSYS^DEF Example < in global definitions > INT .EXT ci^config (_CI^DEF); INT .EXT ss^config (_SUBSYS^DEF); STRING .ciname[0:ZDSN^MAX^CICLASS-1] := [“XXX ”]; STRING .ssname[0:ZDSN^MAX^SUBSYS-1] := [“YYYYYY ”]; < within _STARTUP procedure > BEGIN . . IF _ISNULL (@ci^config := _ADD^CI (ciname)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; IF _ISNULL (@ss^config := _ADD^SUBSYS (ssname)) THEN RETURN ZDSN^ERR^INTERNAL^ERR; . .
_SUCCESSOR^LM DSNM Library Services _SUCCESSOR^LM _SUCCESSOR^LM returns the address of the list member placed on the list immediately after the current list member was added. @next-list-member := _SUCCESSOR^LM ( list ,list-member ); next-list-member returned value INT .EXT is the address of the successor list member. input list is the name of a _LIST. input list-member INT .EXT is a pointer to a current member of list. Considerations • • List members are logically ordered.
_SUCCESSOR^LM DSNM Library Services Examples The following examples use the declarations: _LIST (list); INT .EXT lm (list^member^def); INT .EXT nextlm (list^member^def); !extended pointer to !list member structure !another extended pointer !to list member struct This example scans a list in the forward direction: @lm := _NULL; WHILE _NOTNULL (@lm := _SUCCESSOR^LM (list,lm)) DO BEGIN ...
_THREAD^CONTEXT^ADDRESS DSNM Library Services _THREAD^CONTEXT^ADDRESS _THREAD^CONTEXT^ADDRESS is an INT(32) field, containing the extended address of the command context area, which is allocated to each thread when it is created and persists until the thread terminates. The context area contains a fixed header, followed by a user-defined area.
_THREAD^PROC DSNM Library Services _THREAD^PROC _THREAD^PROC defines a procedure dispatched as part of a thread (a procedure that can be set as a new current thread with _SET^THREAD^PROC, _PUSH^THREAD^PROCSTATE, _POP^THREAD^PROCSTATE, _DISPATCH^THREAD or _SAVE^THREAD^AND^DISPATCH). _THREAD^PROC ( procname ); procname user-provided identifier is the name (a valid TAL identifier) of the procedure.
_THREAD^STATE DSNM Library Services _THREAD^STATE _THREAD^STATE accesses an INT variable that represents the current state of the thread. _THREAD^STATE may be set or tested. _THREAD^STATE Considerations • • • The frame sets the thread state to _ST^INITIAL when it creates a thread. Subsequently, you may alter the thread state as desired; the frame never uses it again. Thread state values less than the library literal _ST^MIN^THREAD^STATE are reserved. State values are always nonnegative.
DSNM Library Services _THREAD^TERMINATION^CODE _THREAD^TERMINATION^CODE _THREAD^TERMINATION^CODE is a define to access a context field that contains the ZDSN^ERR value returned with _RC^ABORT or _RC^STOP. It is designed for use in _COMMAND^TERMINATION^PROC to determine why the thread terminated. _THREAD^TERMINATION^CODE In the case of an _RC^STOP, the _THREAD^TERMINATION^CODE value is 0.
_THREAD^TERMINATION^PROC DSNM Library Services _THREAD^TERMINATION^PROC _THREAD^TERMINATION^PROC defines a procedure responsible for cleaning up the thread’s environment after a command successfully completes or after a thread abnormally terminates. It is the required name of the thread termination procedure for the I process. _THREAD^TERMINATION^CODE may be accessed and/or altered in the thread termination procedure.
_TURNOFF DSNM Library Services _TURNOFF _TURNOFF turns off all the bits in int-var that are on in bit-mask. _TURNOFF ( int-var , bit-mask ); input/output int-var INT:ref is a variable, the bits of which are turned off according to the contents of bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-var to turn off.
_TURNON DSNM Library Services _TURNON _TURNON turns on all the bits in int-var that are on in bit-mask. _TURNON ( int-var , bit-mask ); input/output int-var INT:ref is a variable, the bits of which are turned on according to the contents of bit-mask. input bit-mask INT:value is an INT expression, the one-bits of which identify the bits in int-var to turn on.
_UNGET^LM DSNM Library Services _UNGET^LM _UNGET^LM replaces the last list member removed from a list using _GET^LM. error := _UNGET^LM ( list ,list-member ); error returned value INT is a ZDSN^ERR value indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions. list input is the name of a _LIST. list-member input INT .EXT is a pointer to the member most-recently removed from list with _GET^LM.
_UNPOP^LM DSNM Library Services _UNPOP^LM _UNPOP^LM replaces the last list member removed from a list using _POP^LM. error := _UNPOP^LM ( list ,list-member ); returned value error INT is a ZDSN^ERR value, indicating the outcome of the call. See Appendix B, “DSNM Error Codes,” for error code definitions. input list is the name of a _LIST. input list-member INT .EXT is a pointer to the member most-recently removed from list with _POP^LM.
DSNM Library Services _XADR^EQ _XADR^EQ _XADR^EQ is a Boolean define statement that is TRUE if two possibly null extended addresses are equal (since _NULL can have more than one value). _XADR^EQ ( address1 , address2 ) address1 input INT(32):value is an extended address whose value is compared to address2. address2 input INT(32):value is an extended address whose value is compared to address1.
_XADR^NEQ DSNM Library Services _XADR^NEQ _XADR^NEQ is a Boolean define statement that is TRUE if two possibly null addresses are not equal (since _NULL can have more than one value). _XADR^NEQ ( address1 , address2 ) input address1 INT(32):value is an extended address whose value is compared to address2 . input address2 INT(32):value is an extended address whose value is compared to address1.
B DSNM Error Codes Scope of This Appendix This appendix lists the ZDSN^ERR values that you may send back to the frame in the Z^RESULT field of a formatted output object structure, or that may be returned to you from a call to a DSNM library procedure. Reporting Errors Errors that do not terminate a command must be associated with an object (for instance, an object name that is unknown to the subsystem) and are reported in the Z^RESULT field of a formatted output object structure.
ZDSN Error Codes • • DSNM Error Codes List of any warning or error messages displayed before and after the problem occurred. Any other information, as stated in the explanation of the pertinent error messages. ZDSN Error Codes The following ZDSN^ERR values may be returned to the frame by the command thread in the Z^RESULT field of a formatted output object, or returned to the command thread from a call to a library procedure.
DSNM Error Codes -34 -45 ZDSN^ERR^TKN^REQ ZDSN^ERR^INTERNAL^ERR Unexpected Error: DSNM Component Error Cause. An internal program error or inconsistency occurred. Effect. Command terminated abnormally due to an internal DSNM component error, possibly due to memory corruption. Recovery. Check the EMS event log for the error reported. Stop the I process and then start it again. If the error persists, contact your Tandem representative. -35 ZDSN^ERR^SUBSYSTEM^ERR Subsystem Error Cause.
-51 -51 ZDSN^ERR^SPI^ERR DSNM Error Codes ZDSN^ERR^SPI^ERR Unexpected Error: DSNM SPI Error Cause. A subsystem SPI error occurred. Append the SPI error to the output object as ZDSN^VTY^RESULTTEXT. Effect. The command terminated abnormally. The state of the error object is subsystem-dependent. Recovery. Check the CI message SPI buffer for correctness. Refer to the subsystem management programming documentation for information about the error. -55 ZDSN^ERR^OBJNAME^INV Invalid Object Name Cause.
DSNM Error Codes -64 -71 ZDSN^ERR^ALLOCATESEGMENT^ERR ZDSN^ERR^FS^ERR File System Error Cause. The Guardian file system generated an error during the execution of your command. Effect. The effect depends on the specific file system error. Recovery. Refer to the Guardian User’s Guide for an explanation of the error and its recovery. -67 ZDSN^ERR^CMD^TIMED^OUT Command Timeout Cause. The command timed out before it could be executed. Effect. Your command is not executed. Recovery.
-76 -76 ZDSN^ERR^BADCOMMAND DSNM Error Codes ZDSN^ERR^BADCOMMAND Unexpected Error: Invalid Command Cause. The command is not valid for the subsystem. Effect. The command is not executed. Recovery. Refer to the User’s Guide to DSNM Commands for information on which commands are supported for the subsystem you specified. -77 ZDSN^ERR^UNSUPPORTED^BY^SUBSYS Not Supported by Subsystem Cause. The operation or command modifier is not supported by the subsystem you specified. Effect.
DSNM Error Codes -81 -88 ZDSN^ERR^DUP^KEYWORD ZDSN^ERR^MISSING^OBJTYPE Missing Object Type Cause. You issued a command without specifying the object type, and the object type could not be determined from the information on the command line. Effect. Your command is not executed on the affected objects. Recovery. Reissue the command, specifying the object type explicitly. -82 ZDSN^ERR^BADOBJTYPE Invalid Object Type Cause.
-202 ZDSN^ERR^OBJECTTOOLONG or ZDSN^ERR^OBJTOOLONG -202 DSNM Error Codes ZDSN^ERR^OBJECTTOOLONG or ZDSN^ERR^OBJTOOLONG Object Name too Long Cause. You typed an object name that is longer than the maximum allowable length. Effect. Your command is not executed. Recovery. Reissue the command with a shorter name. -204 ZDSN^ERR^BADARGUMENT Missing or Invalid Library Argument Cause. There is an internal problem in the software that issued the message. Effect.
DSNM Error Codes -212 -217 DSN^ERR^BADLOGON ZDSN^ERR^SYNTAX Invalid Syntax Cause. Your command was syntactically incorrect. Effect. Your command is not executed. Recovery. Verify the syntax of the command, correct it as needed, and reissue the command. See Section 2, “DSNM Commands,” for information. -214 ZDSN^ERR^RESERVEDWORD Reserved Word Misplaced Cause. Your command included a reserved word in the wrong position. Effect. Your command is not executed. Recovery.
Messages From the DSNM Parser DSNM Error Codes Messages From the DSNM Parser The following errors may be generated by the DSNM parser, which interprets DSNM commands before they are executed. Command not recognized Cause. You misspelled a command or issued a command that is not supported. Effect. Your command is not executed. Recovery. Correct and reissue the command. Exceeded max objects Cause. Your command includes more objects than are allowed in a single command. Effect.
DSNM Error Codes Messages From the DSNM Parser error is a positive number, refer to the Guardian Procedure Errors and Messages Manual for an explanation of the file system error and its recovery. If the error is not a file system error, call your Tandem representative. Prepare the necessary information as suggested in “What to Prepare Before Contacting Your Tandem Support Representative” on page B-1. Invalid Object Type Cause. You specified an object type that is not valid. Effect.
Messages From the DSNM Parser DSNM Error Codes No operands Cause. You issued a command that requires operands, but did not specify any. Effect. Your command is not executed. Recovery. Correct and reissue the command. Reserved word misplaced Cause. A keyword, subsystem name, or object type was out of place. Effect. Your command is not executed. Recovery. Correct and reissue the command.
DSNM Error Codes Messages From the DSNM Parser Unexpected error: text Cause. There is an internal problem in the software that issued the message. Effect. The effects of this problem vary, depending on the situation. Recovery. Note the error text and contact a Tandem representative. Prepare the necessary information as suggested in “What to Prepare Before Contacting Your Tandem Support Representative” on page B-1.
Messages From the DSNM Parser B- 14 DSNM Error Codes 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
C Data Defined DSNM SPI Components Scope of This Appendix Internally, DSNM uses the Tandem Subsystem Programmatic Interface (SPI) for command and response message flows. DSNM SPI components (constants and data definitions) are defined in the DSNM SPI Data Definition Language (DDL) and may be identified by the prefix ZDSN^. SPI messages are handled by the frame and are generally hidden from the user-written command thread, but certain SPI DDL constants and structure definitions are required.
EMOD Values Data Definition Language (DDL)-Defined DSNM SPI Components EMOD Values The following constants are the possible Z^EMOD values: Zero (omitted)—Default to ZDSN^EMOD^BRIEF ZDSN^EMOD^BRIEF ZDSN^EMOD^DETAIL ZDSN^EMOD^SUPPRESS SMOD Values The following constants are the possible Z^SMOD values: 0 (omitted)—No default—Command applied regardless of object state ZDSN^SMOD^GREEN / ZDSN^SMOD^UP ZDSN^SMOD^NOT^GREEN / ZDSN^SMOD^NOT^UP ZDSN^SMOD^RED / ZDSN^SMOD^DOWN ZDSN^SMOD^NOT^RED / ZDSN^SMOD^NOT^DOWN ZD
Data Definition Language (DDL)-Defined DSNM SPI Components DSNM State Values Command Object DDL The following structure definition defines an object in a DSNM command.
Error Codes Data Definition Language (DDL)-Defined DSNM SPI Components Error Codes The following constants are the DSNM error codes used most often: ZDSN^ERR^NOERR ZDSN^ERR^INTERNAL^ERR ZDSN^ERR^SUBSYSTEM^ERR ZDSN^ERR^OBJNAME^INV ZDSN^ERR^OBJTYPE^NOT^SUPPORTED | ZDSN^ERR^OBJ^NOT^SUPP ZDSN^ERR^MEMORY ZDSN^ERR^FS^ERR ZDSN^ERR^CMD^NOT^SUPP ZDSN^ERR^UNSUPPORTED^BY^SUBSYS ZDSN^ERR^UNSUPPORTED^BY^I ZDSN^ERR^MISSING^OBJTYPE AGGREGATE Counters The following structure definition defines counters returned in an AG
Data Definition Language (DDL)-Defined DSNM SPI Components DDL Definitions for DSNM Character String Components DDL Definitions for DSNM Character String Components Subsystems and object types in DSNM commands, responses, and configuration are represented by character strings.
DDL Definitions for DSNM Character String Components C- 6 Data Definition Language (DDL)-Defined DSNM SPI Components 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
D Sample I Process Program Code Scope of This Appendix Appendix D provides a sample I process program for a pseudo-subsystem (SPIFFY), illustrating the program model and associated I process development library services described in this manual. Overview of the SPIFFY Subsystem The SPIFFY subsystem consists of SPIFFY manager processes, each controlling a set of SPIFFY objects. A manager supports a programmatic interface consisting of formatted messages.
Sample I Process Program Code SPIFFY Subsystem Programmatic Interface Commands SPIFFY Subsystem Programmatic Interface Commands The SPIFFY subsystem programmatic interface supports informational and state-change commands. Informational Commands The SPIFFY subsystem programmatic interface supports one informational command, TELLABOUT, which applies to objects of all types and returns everything known about the object(s) specified by the command.
Sample I Process Program Code Command and Response Message Formats The program code example in this appendix illustrates the processing of informational commands. The processing of state-change operations is not explicitly illustrated; however, the preliminary processing of NAME, POP, and TYPE values is included (to determine the set of objects on which a state-change operation would be performed).
Command and Response Message Formats Sample I Process Program Code Response Message Format The response message begins with the command message, followed by an error code (ERROR), a count of response objects (RESPONSE^THINGS), and response object details in an object-characteristics array (THING): LITERAL max^response^things = 2; STRUCT spiffy^response^def (*); ! Response message, which ! contains cmd msg struct BEGIN STRUCT cmd (spiffy^command^def); INT error; INT response^things; STRUCT thing (spiffy^th
SPIFFY Subsystem Literal Definitions Sample I Process Program Code SPIFFY Subsystem Literal Definitions Literal definitions for all codes and errors are provided when the SPIFFY subsystem is delivered.
SPIFFY I Process Design Sample I Process Program Code SPIFFY I Process Design To develop an I process, you must map the states of subsystem objects to DSNM states, and a sequence of subsystem commands to the DSNM commands. State Mapping To map the many possible states of subsystem objects to DSNM states requires detailed subsystem knowledge. The mapping should represent the operating state of the subsystem object.
Implementing DSNM Commands Sample I Process Program Code Implementing DSNM Commands DSNM commands are implemented by SPIFFY subsystem commands as follows. Implementing the Informational Commands The DSNM STATUS and INFO commands can be issued by executing the TELLABOUT command and selecting different informational details to return in the output. The SPIFFY subsystem does not support a STATISTICS command or its equivalent.
Managing SPIFFY Through DSNM: Sample Command Output Sample I Process Program Code Implementing an Informational Command on a “*” Operand You can implement an informational command on a “*” operand by first issuing a TELLABOUT command: TELLABOUT NAME * POP * TYPE typecode This ignores HMOD and SMOD. Perform the informational operation on each resulting object, as described in the hierarchy modifier table above.
Sample I Process Program Code DSNM STATUS Command Output DSNM STATUS Command Output Following are examples of STATUS command output: DSNM $spfi > STATUS REACTOR * UNDER $SMGR SPIFFY REACTOR PURPLE UNDER $SMGR SPIFFY BOILER ELEMENT1 UNDER $SMGR Down SPIFFY BOILER ELEMENT2 UNDER $SMGR Pending SPIFFY BOILER ELEMENT3 UNDER $SMGR Up SPIFFY VALVE MIX1 UNDER $SMGR Pending SPIFFY VALVE MIX2 UNDER $SMGR Down SPIFFY VALVE MIX3 UNDER $SMGR Pending SPIFFY CHAMBER COMPOUND1 UNDER $SMGR Up SPIFFY CHAMBER COMPOUND2 UNDE
DSNM STATUS Command Output SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY SPIFFY VALVE CHAMBER CHAMBER CHAMBER BOILER BOILER BOILER VALVE VALVE VALVE CHAMBER CHAMBER CHAMBER Sample I Process Program Code FORMULAZ UNDER $SMGR Up SECRETX UNDER $SMGR Down SECRETY UNDER $SMGR Pending SECRETZ UNDER $SMGR Pending INGREDTA UNDER $SMGR Pending INGREDTB UNDER $SMGR Pending INGREDTC UNDER $SMGR Pending XXX UNDER $SMGR Pending YYY UNDER $SMGR Down ZZZ UNDER $SMGR Pending AAA UN
Sample I Process Program Code SPIFFY SPIFFY DSNM STATUS Command Output CHAMBER AAA UNDER $SMGR Pending CHAMBER CCC UNDER $SMGR Pending DSNM $spfi > STATUS REACTOR * UNDER $SMGR, DOWN SPIFFY BOILER ELEMENT1 UNDER $SMGR Down SPIFFY VALVE MIX2 UNDER $SMGR Down SPIFFY CHAMBER COMPOUND2 UNDER $SMGR Down SPIFFY BOILER STUFFY UNDER $SMGR Down SPIFFY VALVE FORMULAX UNDER $SMGR Down SPIFFY CHAMBER SECRETX UNDER $SMGR Down SPIFFY VALVE YYY UNDER $SMGR Down DSNM $spfi > STATUS REACTOR * UNDER $SMGR, NOT-DOWN SPIFF
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process Sample User-Written Code for SPIFFY Subsystem Interface Process The following is the user-written SPIFFY subsystem interface code, which, when compiled, is bound in with the Tandem I process program frame code to create the SPIFFY I process object file. This example does not illustrate the processing of any state-change commands, nor does it illustrate how to handle command cancellation (_EV^CANCEL). Note.
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process ! ERRORS LITERAL COMMAND^DONE, COMMAND^MSG^TOOSHORT, COMMAND^INVALID, TYPE^INVALID, COMMAND^INVALID^FOR^TYPE, COMMAND^IMPOSSIBLE, THING^NONEXISTENT, POP^NONEXISTENT; literal spiffy^name^len= 20, max^response^things = 2; STRUCT spiffy^thing^things = INT type; INT name^occurs; STRING name [0:spiffy^name^len-1]; INT pop^name^occurs; ! ! ! ! ! STRING pop^name[0:spiffy^name^len-1]; ! For ASSEMBLYs and subordinates IN
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code ! Thread states LITERAL st^new^object = _ST^MIN^THREAD^STATE, st^prilim^done, st^done, st^exec, st^exec^done; ! cx.cf Command flag bit definitions (see cx.
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code ! SPIFFY Subsystem CI and Subsystem configurations STRING .spifclass[0:ZDSN^MAX^CICLASS-1] := "SPIFMON "; STRING .spifsys[0:ZDSN^MAX^SUBSYS-1] := "SPIFFY "; INT .EXT spifmon (_CI^DEF); INT .
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code ------------------------------------------------------------------------------------------------------------------------------------------------------ Command Thread Auxiliary Procs --------------------------------------------------------------------------------------------------------------------------------------------------------------INT PROC append^numeric^resulttext (frameobj^arg,num); INT(32) num; INT .
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code ELSE BEGIN ! FS Error frameobj.FOBJ.Z^RESULT := ZDSN^ERR^FS^ERR; IF (er := append^numeric^resulttext (frameobj, $DBL (inobj.er))) THEN RETURN _RC^ABORT(er); END; _RELEASE^OUTPUT (frameobj); RETURN _RC^NULL; END; _RC^TYPE PROC format^normal^object (obj^arg); INT .EXT obj^arg; BEGIN ! Generate output object for an input object INT .EXT cx (cx^def) = _THREAD^CONTEXT^ADDRESS; INT .
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process ! Return cmd flags for HMOD value INT SUBPROC hmodflags (xhmod); INT xhmod; BEGIN CASE xhmod OF BEGIN ZDSN^HMOD^ONLY -> RETURN c^cmdobj; ZDSN^HMOD^SUBONLY -> RETURN c^subobj; OTHERWISE -> RETURN c^cmdobj + c^subobj; END; END; ! Return cmd flags for SMOD value INT SUBPROC smodflags (xsmod); INT xsmod; BEGIN CASE xsmod OF BEGIN ZDSN^SMOD^RED -> RETURN ZDSN^SMOD^GREEN -> RETURN ZDSN^SMOD^NOT^RED -> RETURN ZDSN^SMOD^
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process ! Return SPIFFY type code for type name INT SUBPROC typecode (tname); STRING .
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code st^new^object -> ! Enter this state each time we need a new object from the ! frame's input object list, which occurs initially and after ! the preceding object has been processed completely. ! Get the next object from the _INPUT.OBJECTLIST; when it’s _NULL, ! we've processed them all. if _ISNULL (@cx.inobj := @inobj := _GET^LM (cx._INPUT.
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process ! Set the current input and output lists for processing ! thread and put the inobj on the input. ! Note: The current^in and current^out list pointers may be ! exchanged several times while processing an object. ! Reference after this initialization should always be ! made through the current pointers rather than to the ! things/other^things lists directly. @cx.current^in := @cx.things; @cx.current^out := @cx.
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code st^done -> ! Whatever objects resulted from executing the command on ! cx.inobj are now on the cx.current^out list. Build the ! thread output for return to the frame. CALL _CLOSE^CI (cx.spif); WHILE _NOTNULL (@outobj := _GET^LM (cx.current^out)) DO BEGIN IF outobj.
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process ! Return object type string from the SPIFFY type code SUBPROC typename (tname, typecode); STRING .
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process INT SUBPROC state^ok (xstate,xcf); INT xstate, xcf; BEGIN CASE xstate OF BEGIN ZDSN^STATE^GREEN -> RETURN ZDSN^STATE^YELLOW -> RETURN ZDSN^STATE^RED -> RETURN OTHERWISE -> RETURN END; _ON _ON _ON _ON (xcf,c^greenstate); (xcf,c^yellowstate); (xcf,c^redstate); (xcf,c^anystate); END; ! Produce a normal (non-error) output object _RC^TYPE SUBPROC normal^object (thing^arg); INT .EXT thing^arg; INT er; BEGIN INT .
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code CASE _THREAD^STATE OF BEGIN st^new^object -> IF _ISNULL (@inobj := @cx.currentobj := _GET^LM (cx.current^in))THEN BEGIN ! Out of input objects; restore caller and continue. ! Note: Calling proc has set the state in which it ! desires to return before saving the thread state ! and dispatching this proc. _RESTORE^THREAD^AND^DISPATCH (_EV^CONTINUE); ! If _restore^thread fails, we fall through to here and ...
Sample User-Written Code for SPIFFY Subsystem Interface Process Sample I Process Program Code FOR k := 0 to cx.r.response^things-1 DO BEGIN IF (rc := normal^object (cx.r.thing[k])) <> _RC^NULL THEN RETURN rc; END; IF cx.r.cmd.response^context THEN BEGIN ! Note: If _SEND^CI produces an error now, something happened ! to the SPIFFY manager after we last talked to it. ! Put object with error into output, even though it may ! have appeared earlier. IF (er := _SEND^CI (cx.spif, cx.cmd, $LEN (cx.cmd), $LEN (cx.
Sample I Process Program Code Sample User-Written Code for SPIFFY Subsystem Interface Process _THREAD^PROC (action^cmd^proc); BEGIN -...
Configuring SPIFFY Into DSNM Sample I Process Program Code Configuring SPIFFY Into DSNM Specify a file containing the following as an IN file to NETCOM: add \SYS.dsnm.subsystem-interface-config.spifi.public-name, & SPIFFY-INTERFACE add \SYS.dsnm.subsystem-interface-config.spifi.default-& processname, $?SPF add \SYS.dsnm.subsystem-interface-config.spifi.open-params, & NOWAIT-DEPTH 15 add \SYS.dsnm.subsystem.spiffy.rank , 4 add \SYS.dsnm.subsystem.spiffy.default-objtype , cogwheel add \SYS.dsnm.subsystem.
Configuring SPIFFY Into DSNM Sample I Process Program Code Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY FLAGS Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY MANAGER *-OBJ-ALLOWED MGR-REQUIRED SPIFMON Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY OBJTYPE 1 SUBSYS Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY
Configuring SPIFFY Into DSNM D- 30 Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY OBJTYPE 4 VALVE REACTOR Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY OBJTYPE 5 CHAMBER REACTOR Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY OBJTYPE 6 ASSEMBLY SUBSYS Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY OBJTYPE 7 COGWHE
Sample I Process Program Code Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY RANK Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM SPIFFY SUBSYSTEM-INTERFACE Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM-INTERFACE-CONFIG SPIFI DEFAULT-PROCESSNAME Record -----SYSTEM SUBSYS CLASS COMPONENT PARAMETER SEQUENCE VALUE \SYS DSNM SUBSYSTEM-INTERFACE-CONFIG SPIFI OPEN-PARAMS Record -
Configuring SPIFFY Into DSNM D- 32 Sample I Process Program Code 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Index A ABORT command command line syntax 2-8 output object requirements 4-12 valid modifiers 4-12 Action modifier ZDSN^AMOD values 4-7 ADD^CI 3-13, 3-46, 5-12, A-5 ADD^SUBSYS 3-13, 5-12, A-7 AGGREGATE command command line syntax 2-10 output object requirements 4-13 valid modifiers 4-13 ALLOFF A-9 ALLON A-10 ALLON^TURNOFF A-11 Altering current thread procedure 3-39 Altering current thread state 3-40 AMOD See Action modifier ANYOFF A-12 ANYON A-13 ANYON^TURNOFF A-14 APPEND^OUTPUT 3-32, 4-10, A-15 ASSIGN stat
D Index Command thread definition 3-3 termination 3-51 See also Thread Commands DSNM See DSNM commands and individual command names DSNMCom 7-5 See also DSNMCom COMMAND^CONTEXT^HEADER 3-17, A-32 COMMAND^PROC procedure 3-14, A-33 COMMAND^TERMINATION^PROC procedure 3-14, A-34 COMPILED^IN^TESTMODE A-35 Compiling in test mode 5-2 required ASSIGN statements 3-11 required ?SOURCE statements 3-9 Component name, defined 3-12 COMPONENT process parameter 5-2 COMPONENT^PARAM 5-11, A-56 CONFIG DSNMCom process paramet
D Index DSNM 1-1 commands components of 4-1 executing from DSNMCom 7-11 overview of how processed 3-6 components of command server 1-8 database interface process (DBI) 1-9 E process 1-10 I process 1-9 object database 1-9 object monitor process (OMON) 1-9 DSNMCom process parameter 7-2 environment running multiple copies 1-13 extending support of 1-14 object states See Object states operations environments 1-13 parser errors 7-17, B-10 process configuration 1-12 process parameter 5-2 process startup functio
E Index DSNMCONF parameters 5-3 accessing nonstandard 5-10 accessing standard 5-8 DSNMCONF^PARAMS 5-9, A-40 E E process function within network management architecture 1-10 object database configuration 1-9 EMOD See Error modifier EMPTY^LIST 3-28, A-41 EMS 1-8 logging errors to 3-53 EMS^EVENT^CRITICAL A-42, A-104 EMS^EVENT^FATAL A-42, A-104 EMS^EVENT^INFO A-42, A-104 END^THREAD^PROC 3-14, A-43 END^THREAD^TERMINATION^PROC 3 -14, A-44 Error codes See ZDSN^ERR codes Error modifier in command line 2-3 ZDSN^E
L Index H HELP command, DSNMCom 7-6 Hierarchy modifier example of implementing D-7 in command line 2-3 when used with hierarchy qualifier 2-6, 4-4 when used with state modifier 2-6, 4-4 ZDSN^HMOD values 4-3 Hierarchy qualifier when used with hierarchy modifier 2-6 Highlight modifier in command line 2-5 HMOD See Hierarchy modifier I I process function of 3-1 function within network management architecture 1-9 testing See DSNMCom INFO command command line syntax 2-11 output object requirements 4-15 valid m
M Index LAST^TIMEOUT^TAG 3-50, A-70 Library services, overview of 3-54 LIST 3-24, A-71 List 3-5 allocating memory for new last member 3-27 declaring list structure 3-24 deleting a member of 3-27 deleting all members of 3-27 extended pointer to 3-25 finding out if empty 3-28 first member 3-25 initializing 3-24 joining two lists 3-28 last member 3-25 logical view of 3-23 next member 3-25 number of members 3-28 previous member 3-25 releasing members to frame 3-32 removing current first member 3-27 removing c
R Index OBJECTLIST declared by _OUTPUT^DEF A-85 example A-78 input object list 3-18 output object list 3-19 OFF A-79 OMON 1-9 ON A-80 OPEN command, DSNMCom 7-7 OPEN^CI 3-47, A-81 Operations environments 1-13 OUTPUT 3-19, A-84 Output list member 3-22 Output object list 3-5 fields filled in by command thread 4-10 in command context 3-15 releasing members to frame 3-32 _OUTPUT^DEF structure 3-19 OUTPUT^DEF 3-19, A-85 OUTPUT^LM^HEADER 3-22, A-86 P Parameters global 5-5 class 5-5 component 5-5 general 5-6 loc
S Index S SAVE^THREAD^AND^DISPATCH 3-43, A-107 Scanning a list 3-26 SEND^CI 3-47, A-108 SET^THREAD^PROC 3-39, A-111 SET^TIMEOUT 3-50, A-112 SHOW command, DSNMCom 7-10 SIGNAL^EVENT 3-35, A-113 Simulating frame events 3-36 SMOD See State modifier START command command line syntax 2-15 output object requirements 4-16 valid modifiers 4-16 Startup message DSNMCONF parameters 5-3 See also DSNMCONF parameters format of 5-1 process parameters 5-2 See also Process parameters retrieving parameters from 5-4 standard
Z Index T X TERM-START-SVR 1-6 Test mode 5-2 compiling in 5-2 Test utility See DSNMCom TESTMODE process parameter 5-2 Thread 3-3 declaring thread procedures 3-14 See also Current thread Thread state altering 3-40 determining 3-40 initial state 3-40 restoring 3-43 saving 3-43 saving and restoring 3-40 THREAD^CONTEXT^ADDRESS 3-17 THREAD^PROC 3-14, A-125 THREAD^STATE A-126 THREAD^TERMINATION^CODE A-127 THREAD^TERMINATION^PROC 3-14, A-128 Timeouts 3-50 TURNOFF A-129 TURNON A-130 XADR^EQ A-133 XADR^NEQ A-13
Special Characters Index ZDSN^ERR^SUBSYSTEM^ERR 3-53 ZDSN^MAX^TEXT 4-10 ZDSN^MOD^DEF 4-2 ZDSN^STATE^DOWN 4-7 ZDSN^STATE^GREEN 4-7 ZDSN^STATE^NULL 4-8 ZDSN^STATE^PENDING 4-7 ZDSN^STATE^RED 4-7 ZDSN^STATE^UNDEFINED 4-8 ZDSN^STATE^UNKNOWN 4-8 ZDSN^STATE^UP 4-7 ZDSN^STATE^YELLOW 4-7 ZDSN^VTY^COUNTERS 4-10, 4-13, A-15, A-16 ZDSN^VTY^ERRTEXT 4-10, A-15, A-16 ZDSN^VTY^RESULTTEXT 4-10, A-15, A-16 ZDSN^VTY^TEXT 4-10, A-15, A-16 Z^HMOD applying to object list members 4-9 Z^SMOD applying to object list members 4-9
2. DSNM Commands Contents New and Changed Information iii About This Manual xv Notation Conventions xix 1.
3. I Process Development Process Contents The STOP Command 2-21 The UPDATE Command 2-23 3.
Contents 4.
5. DSNM Process Startup Functions Contents The START Command 4-16 The STATISTICS Command 4-17 The STATUS Command 4-18 The STOP Command 4-20 5.
Contents A. DSNM Library Services Using the Break Key 7-4 Setting Security Parameters in DSNMCom 7-5 The DSNMCom Commands 7-5 CLOSE Command 7-5 EXIT Command 7-5 FC Command 7-6 HELP Command 7-6 OPEN Command 7-7 QUIT Command 7-7 RESET Command 7-7 SET Command 7-7 SHOW Command 7-10 Executing DSNM Commands 7-11 DSNMCom Messages 7-12 DSNM Parser Errors 7-17 A.
A.
A.
B. DSNM Error Codes Contents _ST^MIN^THREAD^STATE A-119 _SUBSYS^DEF A-120 _SUCCESSOR^LM A-122 _THREAD^CONTEXT^ADDRESS A-124 _THREAD^PROC A-125 _THREAD^STATE A-126 _THREAD^TERMINATION^CODE A-127 _THREAD^TERMINATION^PROC A-128 _TURNOFF A-129 _TURNON A-130 _UNGET^LM A-131 _UNPOP^LM A-132 _XADR^EQ A-133 _XADR^NEQ A-134 B.
D. Sample I Process Program Code Contents -81 -82 -86 -88 -202 ZDSN^ERR^MISSING^OBJTYPE B-7 ZDSN^ERR^BADOBJTYPE B-7 ZDSN^ERR^REQ^KEYWORD^MISSING B-7 ZDSN^ERR^DUP^KEYWORD B-7 ZDSN^ERR^OBJECTTOOLONG or ZDSN^ERR^OBJTOOLONG B-8 -204 ZDSN^ERR^BADARGUMENT B-8 -206 ZDSN^ERR^NOTPUSHED B-8 -207 ZDSN^ERR^LIB^BADVALUE^OMITTED B-8 -212 ZDSN^ERR^SYNTAX B-9 -214 ZDSN^ERR^RESERVEDWORD B-9 -216 ZDSN^ERR^CMDERROR B-9 -217 DSN^ERR^BADLOGON B-9 Messages From the DSNM Parser B-10 C.
Index Contents Index-1 Implementing DSNM Commands D-7 Managing SPIFFY Through DSNM: Sample Command Output D-8 Using DSNMCom to Test the SPIFFY I Process D-8 DSNM STATUS Command Output D-9 Sample User-Written Code for SPIFFY Subsystem Interface Process D-12 Configuring SPIFFY Into DSNM D-28 Index 10 Index-1 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Examples Examples Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide— 109759 1
Examples 2 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Figures Figures Figure 1-1. Figure 1-2. Figure 1-3. Figure 1-4. Figure 3-1. Figure 3-2. Figure 3-3. Figure 3-4. Figure 3-5. Figure 3-6. Figure 3-7. Figure 3-8.
Figures 2 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
Tables Tables Table 3-1. Table 4-1. Table 4-2. Table 7-1. Table 7-2. Table A-1.
Tables 2 109759 —Distributed Systems Network Management (DSNM) Subsystem Interface Development Guide
