1.0;itest (IOS test), revision 1.0, 85/12/19 IOS_TEST -- Test IOS_$ calls usage: IOS_TEST [-INIT] FORMAT IOS_TEST [-INIT] IOS_TEST is a program for testing type managers that manage input and output to objects. IOS_TEST allows you to open a stream to any type of object and then use selected IOS calls on the open stream. With IOS_TEST, you can open streams to existing or new objects. For more information on using IOS_TEST to test type managers, see Using the Open System Toolkit for Extending the Streams Facility. Complete descriptions of the IOS_TEST interactive commands are available in the DOMAIN System Utilities manual. OPTIONS -INIT Call the IOS_$INITIALIZE routine (within a type manager) at startup time. COMMANDS SUMMARY IOS_TEST prompts for commands. Any valid, unambiguous prefix of one of the following commands will suffice. Each command calls the IOS call with a similar name. For example, the CLOSE command calls IOS_$CLOSE. _______________________________________________________________________________ SYNTAX FUNCTION (abbreviation shown in uppercase) _______________________________________________________________________________ CHANGE_PATH_NAME stream-id pathname Changes the pathname of an object. CLOSE stream-id Closes a stream. CREATE create-mode [open-options] pathname typename Creates an object and opens a stream to it. DELETE stream-id Deletes an object and closes the associated stream. DUP stream-id stream-id Creates a copy of a specified stream ID. EQUAL stream-id-1 stream-id-2 Determines whether two stream IDs refer to the same object. EXPORT stream-id Simulates stream passing via a PGM_$INVOKE system call. This command tests a type manager's export and import procedures. FORCE_WRITE stream-id Forcibly writes an object and the directory containing the object to "stable" storage. GET [put-get-option] stream-id count Copies data from a stream into a buffer. INQ_BYTE_POS [pos-opt] stream-id Returns the byte position of the stream marker. If you omit a position option, the default is the current position of the stream marker. INQ_CUR_REC_LEN stream-id Returns the length of the record at the current stream marker. INQ_FILE_ATTR stream-id Returns object usage attributes. INQ_FLAGS stream-id Returns the attribute set of an object's type manager. INQ_FULL_KEY [pos-opt] stream-id Returns a full seek key. If you omit a position option, the default is the current position of the stream marker. INQ_PATH_NAME [name-type] stream-id Returns the pathname of the object to which a stream is open. If you omit a name-type, the default is -ROOT. INQ_REC_POS [pos-opt] stream-id Returns the record position of the stream marker. If you omit a position option, the default is the current position of the stream marker. INQ_REC_REM stream-id Returns the number of bytes remaining in the current record. INQ_REC_TYPE stream-id Returns the record type of an object. INQ_SHORT_KEY [pos-opt] stream-id Returns a short seek key. If you omit a position option, the default is the current position of the stream marker. INQ_TYPE_UID stream-id Returns the type UID of an object. LOCATE stream-id count Reads data from a stream, returning a pointer to the data (rather than copying the data to a buffer). OPEN [open-options] pathname Opens a stream to an existing object. PUT [put-get-options] [-NL] stream-id string Writes data into an object. The -NL option inserts a newline character at the end of the string, the default writes only the data. REPLICATE stream-id stream-id Creates a copy of a specified stream ID. SEEK [-RELATIVE [-MINUS]] [-RECORD] stream-id count Performs an absolute or relative seek using byte or record positioning. If you omit the -RELATIVE option, the default is an absolute seek. If you omit the -MINUS option, the default is to seek forward, towards the end of the file. If you omit the -RECORD option, the default is to seek by bytes. SEEK_FULL stream-id recadr byteadr Performs a seek using a full (8-byte) seek key. SEEK_SHORT stream-id key Performs a seek using a short 4-byte seek key. SEEK_TO_BOF stream-id Positions the stream marker to the beginning of an object. SEEK_TO_EOF stream-id Positions the stream marker to the end of an object. SWITCH stream-id stream-id Switches a stream from one stream ID to another stream ID. TRUNCATE stream-id Deletes the contents of an object following the current stream marker. _______________________________________________________________________________ Use one of the following to specify 'create-mode'. These options correspond to the IOS_$CREATE_MODE_T data type. -NO_PRE_EXIST Returns an error if object already exists. -PRESERVE Saves contents of object, if it exists, opens object, and positions stream marker at BOF. -RECREATE Deletes existing object and creates new one of the same name. -TRUNCATE Opens object, then truncates the contents. -MAKE_BACKUP Creates a backup (.BAK) file when closed. -LOC_NAME_ONLY Creates a temporary unnamed object, uses pathname to specify location of object, and locates it on the same volume. _______________________________________________________________________________ Use one of the following to specify 'name-type'. These options correspond to the IOS_$NAME_TYPE_T data type. -LEAF Specifies leaf name regardless of object's name. -NDIR Specifies leaf name if object's name is a name in current naming directory; otherwise, specifies full pathname. -NODE Specifies name relative to the root directory if object is a name in boot volume; otherwise, specifies full pathname. -NODE_DATA Specifies leaf name if object's name is a name in current 'node_data directory; otherwise, specifies full pathname. -ROOT Specifies full pathname, for example, //node/sid/file. -WDIR Specifies leaf name if object's name is a name in current working directory; otherwise, specifies full pathname. _______________________________________________________________________________ Use one or more of the following to specify 'open-options'. These options correspond to the IOS_$OPEN_OPTIONS_T data type. -NO_Delay IOS_$OPEN does not wait for the open to complete before returning. -Write Permits writing data to a new object. -UNREGulated Permits concurrent writing (unregulated read and write access) to the object. -END_OF_FILE Positions stream marker at EOF at open. -INQuire_only Opens object for attribute inquiries only. _______________________________________________________________________________ Use one of the following to specify 'pos-opt'. These options correspond to the IOS_$POS_OPT_T data type. -BOF Returns key for end-of-file (EOF) marker. -EOF Returns key for beginning-of-file (BOF) marker. _______________________________________________________________________________ Use one or more of the following to specify 'put-get-options'. These options correspond to the IOS_$PUT_GET_OPTS_T data type. -COND Gets or puts data conditionally. If the data is not available, returns with a status indicating that condition. -PREview Determines if a put/get would succeed, but does not actually perform data transfer. -PARTial_record Puts the data, but does not terminate the record. -NO_REC_bndry Ignore record (line) boundaries. DEBUGGING MANAGERS Under normal conditions, user-written managers are dynamically loaded into the opener's address space. While you can use IOS_TEST to test such managers, the manager code itself can not be debugged using DEBUG at the present time. To debug managers using IOS_TEST, you must follow the convention that your manager contains no "main program" (PROGRAM in Pascal, "main" in C). Instead, the initialization for your manager (the part that calls TRAIT_$MGR_DCL, etc.) should be placed in a procedure named "ios_$initialize". To debug your manager module using IOS_TEST, bind all the pieces of your manager together with "/com/itest". Then use DEBUG on the result of the bind and give the -INIT switch. For example: $ bind -b my_itest <<! my_mgr.bin my_mgr_uid.bin /sys/traits/io_traits /com/itest ! $ debug -src my_itest -init