cfunc.introduction Introductory/C Functions, tcl.printronix Verb: Access/TCL, intro Introductory/Access: Modifiers


Command cfunc.introduction Introductory/C Functions
Applicable release versions: AP 6.1
Category C Functions (120)
Description outlines how to access the Pick environment from the "C" programming language.

The functionality of the Pick environment is available from the C programming language. This is made available through a set of functions and macros defined in the include file "CPuser.h".

Library Format

Functions within the library have the following general structure:



_CP_xxx is a general pattern for the name. It is always prefixed with _CP_ to avoid naming conflicts with standard libraries and is suffixed with an entirely lower-case tag like _CP_execute. Macros are provided using the same model, but they use uppercase tags like _CP_SLEN.

arg0 - argi are arguments.

rc is the result code. Almost all functions return an integer result. This result is -1 if an error occurs, and the global variable _CP_errno is set to one of the following error codes:

PE_NFILE Not enough memory to open more files
PE_ACCESS Cannot access file
PE_TRUNC String trunctated due to lack of memory
PE_NOSPACE Could not allocate workspace
PE_LOCK Item is locked
PE_INVAL Invalid call
PE_NONUM Not a number
PE_BADF File not opened
PE_MISSING File not found
PE_CONV Conversion error
PE_BADATTR Bad attribute
PE_TMOUT Input time out
PE_TAPE Tape error
PE_PROC Proc read error
PE_EOF End of file/item
PE_CALLMAIN Tried to call a main as a subroutine
PE_NOTROOT Bad root variable
PE_ILL_KEY Bad key operator
PE_LONG_STR Too long a string for heading
PE_LEVEL Debugger entered
PE_DEBUG Debugger entered
PE_BAD_PARAMS Too many parameters on a call
PE_LOAD_ERR Unable to load Flash subroutine
PE_END_LIST No more items on select
PE_GETSEND Bad pib on get/send
PE_MISCERR Miscellaneous logon error
PE_INIT Virtual machine not booted or attached
PE_BADUSER Bad user ID or user password
PE_BADMD Bad MD or MD password

General Usage

To use this library, the user makes a call to _CP_logon() at the beginning of the C program to connect to the Pick virtual machine. This call goes through the normal Pick logon activities, but suppress all user prompts and messages. Note that neither the user nor the MD macro will be executed. After logging on, the user has full access to the Pick database using C calls which provide functionality previously available only through Pick/BASIC. When the C program completes, the user must issue a _CP_logoff() call to terminate the Pick connection.

String Handling

The standard C string type is not sufficient for handling the dynamic nature of Pick strings, so a hybrid data type has been created called CPSTR. This data type provides allocation, deallocation, and resizing of strings at a much higher performance level than that obtained using malloc(), and free() with C strings. The internal structure of a CPSTR is reserved and SHOULD NOT BE ACCESSED DIRECTLY. Failure to abide by this rule will DEFINITELY GUARANTEE INCOMPATIBILITY WITH FUTURE RELEASES. The structure of a CPSTR is as follows:

Header Internal use only - DO NOT MODIFY
String - Character array containing the actual string
Terminator - A single character used for termination
Footer Internal use only - DO NOT MODIFY

The following macros are provided to access all desired portions of a CPSTR structure.

_CP_SLEN(s) returns the current length of a string. This length does not include any terminating character like a segment mark or a null character.

_CP_SADDR(s) returns a (char *) to the actual string data which may or may not be terminated by a 0x00. Note that this (char *) MUST NOT be passed to the free() C function or to any C function which may try to use free() on the (char *).

Allocation of CPSTR strings is accomplished via special allocation routines. CPSTR strings MUST NOT be allocated with the C function malloc(). The allocation routines provided set necessary internal flags, and they are much more efficient than malloc. Note that these routines create dynamic structures which must be deallocated with the routines listed below.

_CP_str_alloc(l) returns a CPSTR of length l. The actual string data portion of the string is undefined.

_CP_mkstrl(char *s, int l) Returns a CPSTR from a C string s, of length l. The string portion of the CPSTR will contain a copy of the C string's data.

_CP_mkstr(char *s) Returns a CPSTR from a C string s terminated by a 0x00. The string portion of the CPSTR will contain a copy of the C string's data. This function is less efficient than _CP_mkstrl as it must scan the C string to determine its length.

_CP_str_realloc(CPSTR **s, int l) Resizes the CPSTR s.

_CP_str_free(CPSTR ** s) Frees the desired string s.

Note that when the _CP_logoff call is executed, all CPSTR's remain valid, but they may not be passed to any of the _CP_ routines. All CPSTR's are properly cleaned up when the C program exits.

The user must be careful with termination. Any _CP_ routine may modify the termination character. Therefore, the user must use the _CP_TERM() macro to terminate CPSTR's with a 0x00 if it is necessary to pass the string portion of it to a standard Unix routine.

Note that it is necessary to free strings only when the user has finished with them completely. All resizing of strings is accomplished automatically by the _CP_routines. For example, if a process repeatedly reads data into a buffer via the _CP_read call, this buffer will be automatically resized to fit the new data within the _CP_read call at every read.

Environment Setting

To make it easier to handle the differences between the standard behavior of Unix programs and the standard behavior of Pick programs, two calls are provided that set the "environment" to either Pick or Unix.

_CP_pick_env() sets the application to a standard "Pick" environment. When using this setting, all terminal input and output must be done via Pick routines ONLY.

_CP_unix_env() sets the application to a standard "Unix" environment. With this setting, all terminal input and output must be done directly from "C". The program must not "execute" or "call" any Pick routines which may "crt" or "print" something through Pick.

The original logon to Pick calls _CP_pick_env(). After that, the user may use these routines to switch environments as often as desired, but the environment functions are fairly expensive so they should only be used when switching environments is absolutely necessary. To ensure the correct functionality of the Unix shell, the system automatically calls _CP_unix_env() when the user logs off the of the Pick virtual machine.

Break Key Handling

When logged into Pick, the default action for the break key is set to push a level or drop into the debugger as is standard in Pick. This behavior may be changed however by using the following calls:

_CP_unix_break() causes the break key to force a logoff from Pick and terminate the C program with an exit() call. This simulates the standard behavior of the break key in a Unix application.

_CP_pick_break() causes the break key to behave in the Pick manner.

Handling General Pick Interrupts

Pick interrupts, besides breaks, such as messages, may not be masked, but they may be detected (after the occurence) by interrogating the _CP_interrupt variable. This integer location contains the same information available in BASIC from the system(37) function. However, examination of _CP_interrupt is much more efficient when programming in C.

Custom Signal Processing

The Pick libraries make extensive use of signal processing. Because of this, the practice of reprogramming signals within a C application using Pick C routines is strongly discouraged. However, if it is absolutely necessary, there are several rules which must be followed.

When calling _CP_logon, all signals are re-routed to Pick signal handlers.

When calling _CP_logoff, all signals are re-routed to Unix defaults. Note that they are not necessarily reset to the values they held before the _CP_logon call.

The signal SIGUSR2 must never be reprogrammed as it is used by Pick for logging off and sending messages.

Because interrupts may occur within critical code, the user may not make calls to _CP_ functions within signal handlers.
The following program prints the name of all users in the users file.

#include "CPuser.h"

  CPSTR * machine = _CP_mkstrl("pick0",5); /* default */
  CPSTR * user = _CP_mkstrl("dm",2);
  CPSTR * md = _CP_mkstrl("dm",2);

  CPSTR * filename = _CP_mkstrl("users",5);
  int     fd = -1;
  int     sl = -1; /* initialize select list */

  CPSTR * item_id = _CP_str_null;

/* Logon onto "pick0" as "dm" in the "dm" md */

  if (_CP_logon(machine, user, _CP_str_null, 
      md, _CP_str_null, -1, 0) < 0)
    printf("Logon error %dn", _CP_errno);

  /* done with machine, user, and md */


  /* Make the break key terminate the program */


  /* Open the users file into the file descriptor fd */

  if (_CP_open(&fd, _CP_str_null, filename) < 0)
    printf("Could not open users file n");

  /* done with filename */

  /* Do a raw select of "users" and store that select
     list in the select list descriptor sl */

  _CP_select(fd, &sl, 0);

  /* Switch to Unix-type I/O so we can use printf */


  /* repeatedly read item-ids and print them as a list */

  /* Note how item_id is repeatedly passed to _CP_readnext.
     Each time, _CP_readnext will resize it if necessary,
     and write the next item-id into that CPSTR  */

  while (_CP_readnext(&item_id, &sl, 0, 0) >= 0)
    _CP_TERM(item_id); /* terminate for printf */
    printf("%sn", _CP_SADDR(item_id));

  /* done with item_id - Not absolutely necessary since */
  /*   it will be cleaned up when we exit               */


  /* logoff and return */

  return 0;
Related cpstr*


Command tcl.printronix Verb: Access/TCL
Applicable release versions: AP, R83
Category TCL (746)
Description sets the "vfu" (vertical formlength unit) for printronix printers only.

The vfu setting include a page length, skip perfs, and vertical tabs.
Related tcl.okidata


Command intro Introductory/Access: Modifiers
Applicable release versions:
Category Access: Modifiers (8)
Description general description of Pick.

Pick is an on-line computing environment that allows many users to share a computer and a data base. It is a generalized data base management language and system that provides tools to manage information in a flexible, efficient, and timely manner. The essence of developing an application with Pick is to define the problem in terms of information and relationships between information.

The Pick environment has been used to develop thousands of application packages used by more than two million people since the late 1960’s. Some of the reasons forPick's success are

- Applications can be developed faster and easier with Pick than with traditional systems.

- Applications written in Pick run faster than those written in traditional languages.

- Pick uses fewer resources - cpu, disk, and memory - due to its unique data structure and processing techniques. Pick makes micros perform like mainframes.

- Pick makes users more productive. Users conserve time and resources and can operate applications more effectively and efficiently.

- The multibillion dollar Pick marketplace is growing nearly 50 percent per year with more than 4,000 commercial applications available.

- Pick is available on more computers than any other single environment. Usage of the Pick standard guarantees lifetime hardware freedom. Applications written in Pick today will run on the computers of the future.

The Pick System is a multi-user system. It supports many terminals and runs many jobs simultaneously. Processing originates with commands entered at the keyboard using Terminal Control Language (TCL) and Access statements, which are a combination of verbs and parameters contained in files called master dictionaries (MDs). Each set of interrelated files (a data base) in the Pick System is organized around a master dictionary. The master dictionary contains the verbs (both provided with the system and cataloged programs that are part of an application), macros, menus, connectives, and file names needed to process the information in its data base.

The system can be customized to fit the needs of each user. The master dictionaries to which a user has access and the items in those master dictionaries determine the features available to that user. For example, the master dictionary for personnel might include all employee information and can be accessed by one set of users, while the procedures master dictionary might contain procedures on company policy and can be accessed by a different set of users. Furthermore, access to features within a master dictionary may be limited through various security features, such as user privilege levels and update and retrieval lock codes.

What is Advanced Pick?

The most recent version of the Pick System, Advanced Pick, retains all the functionality of earlier R83 and Open Architecture versions, while adding tools supporting dramatic improvements in the way applications are developed.

In Advanced Pick, an application is created with minimal source code. This is achieved by utilizing the inherent file structures and many application generation tools provided by the operating system. These tools include the Update and Output processors, processing codes, extended Access, and Pick/BASIC capabilities, as well as macro and menu utilities.

Level pushing provides the ability to interrupt a process and invoke any of these other tools on a new level. The interrupted process is pushed onto a stack and can be resumed at the exact location it was interrupted. Up to 16 levels can be pushed. This enhanced system mobility is a boon to development activities.

The improved B-tree structure allows for indexing and enhanced file searching capabilities. Processing codes, residing in three specific attributes of a dictionary item (the input conversion, correlative, and output conversion attributes), provide the ability to maintain and update files without the need of a Pick/BASIC program. These processing codes are used by the Pick System processors to define operations on data within the associated files at the system rather than program level.

The processing codes include:
- Algebraic functions,
- Assembly code executions,
- Pick/BASIC subroutine calls,
- Edit patterns,
- Input and output formats,
- Data conversions,
- If..then..else constructs.

The primary user interface to Advanced Pick is the Update processor. The Update processor is a dictionary-driven, full-screen editor and data processor. Refer to the "Update Processor" Introductory topic at the front of this book and the entry "Update Processor" in the body of the Reference Manual for more information.

Several sample accounts are provided with the system to help you get acquainted with the power of Advanced Pick. One of these accounts is the Personal Assistant (PA) account. The PA account demonstrates the features of Advanced Pick by through example of a complete (mini) application that itemizes names, addresses, phone numbers; writes checks and balances bank statements; and prepares and prints reports.

Another sample account is the Quality Assurance (QA) account. The QA account is made up of programs that can be used to test system functions and commands. QA also contains an option that can be used to report bugs and suggest enhancements to the Pick System.

Installing Advanced Pick

Pick Systems has provided a state-of-the-art operating system which is portable to many different hardware configurations, giving the user the most up-to-date system-level capabilities, plus the ability to upgrade hardware without the fear of needing to redevelop software. Current implementations include releases operating in conjunction with Unix on a variety of RISC-based systems, several native PC-based versions, a version supporting up to three users running as an MS-DOS application, DG/UX, SCO-Unix versions, and others. Refer to the installation guide that came with your Advanced Pick package for detailed installation instructions.