Developer Utilities :TESTNAP commands

Testnap

--------------------------------------------------------------------------------


Dependencies

Syntax

Parameters

Testnap Commands

Error Handling

Error Example 1

Error Example 2

Example


--------------------------------------------------------------------------------

The testnap utility allows a developer to manually interact with the Infranet® server by establishing a PCM connection with the Connection Manager (CM), and then executing PCM operations using that connection. Using testnap, a developer can:


create input flists

save input and output flists

send opcodes

view return (output) flists

create, view, modify, and delete objects and their fields

open, commit, and abort transactions
For examples and information on using testnap, see Testing Your Applications and Custom Modules.

Opcode Workbench, part of the Developer Center offers similar functionality in a GUI-based application. See Testing Your Applications and Custom Modules and the Opcode Workbench help system for detailed information.

Dependencies



The testnap utility requires a pin.conf configuration file to connect to your Infranet system. You can either use the CM's pin.conf file, or run testnap from a directory that contains a suitable pin.conf file, such as Infranet_home/sys/test.

The testnap utility relies on POID logins and types to identify the specific account or storable class to modify. A POID database number is required as a placeholder only.

The necessary pin.conf information is:

- nap cm_name hostname # Name of the system where the cm is running.- nap userid 0.0.0.1 /service/pcm_client 1 # Database number, 0.0.0.1 by default.- nap login_type 1 # Type 1 means login with password.- nap login_name root.0.0.0.n # Username testnap uses to log in to Infranet.- nap login_pw password # Password is "password" by default. Differs from one Infranet installation to another. - nap cm_ptr ip hostname 11960 # CM pointer: protocol hostname port. Allows multiple CM's to be specified in a pin.conf file. The application will try them consecutively until one works or there are no more "cm_ptr" entries.

The correct path to the shared libraries must also be configured. The library path is configured by default to point to the standard libraries in infranet_home_dir/lib. If the libraries are not in infranet_home_dir/lib, then you must set the library path environment appropriately.

Syntax



% testnapnap (pid)> command args

Parameters



The testnap utility allocates numerous internal buffers, which are used to store object or flist fields. Buffers are referenced by integers of the user's choice. Every time a new buffer is referenced, testnap allocates that new buffer.


If you do not specify a buffer number for a command that expects one, you will be prompted for a buffer number.

The meta keyword causes testnap to display the size of external buffer fields. By default, the contents of external buffer fields are displayed.
Testnap Commands



r ((token file buf

Read an flist or object from a file and put it in a testnap buffer. The ((token operator causes testnap to read from stdin until the token string is read.

r+ ((token file buf

Read and append flist to existing buf. The ((token operator causes testnap to read from stdin until the token string is read.

w buf file

Write contents of testnap buffer to a file.

w+ buf file

Append contents of a testnap buffer to the same file.

l

List the testnap buffers that are currently in use.

d buf

Display a testnap buffer.

! cmds args

Run a shell command (for UNIX systems only).

s buf

Save an flist or object from the input buffer to a testnap buffer.

( file

Execute cmd script.

p (property> (value>

Display or set properties.

q

Quit this program.

h, help,?

Print usage help message.

create buf | poid

Create an object. Run PCM_OP_CREATE_OBJ and print the return flist to stdout. The poid keyword causes the poid id of the object that is created to be the poid id specified in the input flist.

delete buf | - (db> (type> (id>

Delete an object. Run PCM_OP_DELETE_OBJ and print the return flist to stdout. The poid of the object to be deleted can be specified on the command line.

robj buf | - (db> (type> (id> meta

Read an object. Run PCM_OP_READ_OBJ using either the poid in the flist in buf, or the poid specified on the command line. Prints the return flist (the contents of the object) to stdout.

rflds buf meta

Read fields. Run PCM_OP_READ_FLDS using the flist in buf, and print the return flist to stdout. Each field (or row) in the field list must be in a valid flist format. The values for the last field are arbitrary, but must be valid for their type. For example, you have to include "" for STR fields and (some number) for a TSTAMP field. If either of these fields are blank, an error is returned.

wflds buf

Write fields. Run PCM_OP_WRITE_FLDS and print the return flist to stdout.

dflds buf

Delete fields. Run PCM_OP_DELETE_FLDS and print the return flist to stdout.

search buf meta count

Search. Run PCM_OP_SEARCH and print the return flist to stdout. The count operator sets the PCM_OPFLG_COUNT_ONLY flag, which causes search to return only the number of matches found by the search. The count is returned as the ELEM_ID of the RESULTS array on the output flist.

ssrch buf meta

Step-search. Run PCM_OP_STEP_SEARCH and print the return flist to stdout.

snext buf meta

Step-search next. Run PCM_OP_STEP_NEXT to get the next object in a step search, and print the return flist to stdout.

send buf

End step-search. Run PCM_OP_STEP_END and print the return flist to stdout.

gdd buf | - (db> (type> (id>

Get data dictionary. Run PCM_OP_GET_DD and print the return flist to stdout. The poid can be specified on the command line.

sdd ( flags> buf

Set data dictionary. Run PCM_OP_SET_DD and print the return flist to stdout.

sort buf sort_buf descending_flag

Read contents of buf, sort it non-recursively using the template in sort_buf, and print the sorted flist to stdout. Available on UNIX only. The descending flag is optional, with 0 (the default) indicating ascending order, and any non-zero integer indicating descending order.

Sorting is not implemented for the following:


POID

BINSTRS

BUFFERs

ERRBUFS
The number of ARRAY elements in the sort specification is ignored. Use 0. Sort specifications just need valid numbers. The numbers are not necessarily valid or desired values for the current sort; they are basically required place-holders.

rsort buf sort_buf descending_flag

Recursive sort. Read contents of buf, sort it recursively using the template in sort_buf, and print the sorted flist to stdout. Available on UNIX only. The descending flag is optional, with 0 (the default) indicating ascending order, and any non-zero integer indicating descending order.

open ro|rw|lock buf | - (db> (type> (id>

Open transaction. Run PCM_OP_TRANS_OPEN and print the return flist to stdout.

commit

Commit the current transaction. Run PCM_OP_TRANS_COMMIT and print the return flist to stdout.

abort

Cancel the current transaction. Run PCM_OP_TRANS_ABORT and print the return flist to stdout.

inc buf

Increment one or more fields of an object. Run PCM_OP_INC_FLDS and print the return flist to stdout.

noop buf

Run non-operational opcode. Run PCM_OP_TEST_LOOPBACK on that database and print the return flist to stdout.

pass buf

Run a pass_thru op to server. Run PCM_OP_PASS_THRU, an extension op that just sends an flist to a DM that supports it.

xop op flag buf

Run opcode op with flags set to flag, the contents of buf as the input flist, and print the sorted flist to stdout.

id

Print user and session ID.

echo string

Echo a string.

Error Handling



If an error occurs, the contents of the error buffer (ebuf) which corresponds to the error are written to stderr.

Error Example 1
# Delete attempt with the - argument missing:pin@demo5-668> testnap===> database 0.0.0.1 from pin.conf "userid"nap(27459)> delete 0.0.0.1 /account 1ERROR: bad number "0.0.0.1"no object to use for delete

Error Example 2
# Attempt to read a non-existent object:nap(10191)> robj - 0.0.0.1 /account 11988PCM_OP_READ_OBJ failed: err 3:PIN_ERR_NOT_FOUND, field 0/16:PIN_FLD_POID, loc 4:PIN_ERRLOC_DM, errclass 4:PIN_ERRCLASS_APPLICATION, rec_id 0, resvd 30001nap(10191)>

For more information on the error buffer, see Understanding API Error Handling and Logging.

Example



For an extensive set of examples refer to the Examples section of Testing Your Applications and Custom Modules.