Chapter 21
Subroutine Libraries

This chapter lists the names of the subroutines in the libraries mentioned in Chapter 13, together with brief descriptions of their functions. Its purpose is to help you find quickly what functions are available. It does not specify argument lists — this would have doubled the size of the chapter and made it much more cluttered. Argument lists are specified in the original documentation, which is referenced on the title line.

21.1 Parameter system

21.1.1 PAR — Parameter system

[APN/6]

The parameter system routines are listed below. The letter ‘d’ stands for the dimensionality:

The letter ‘t’ stands for one of the five HDS data types:

There are no PAR_DEFVx routines.

21.2 Data system

21.2.1 NDF — NDF data structure access

[SUN/33]

Parameter —

NDF_ASSOC:

Associate an existing NDF with a parameter.

NDF_CINP:

Obtain an NDF character component value via the parameter system.

NDF_CREAT:

Create a new simple NDF via the parameter system.

NDF_CREP:

Create a new primitive NDF via the parameter system.

NDF_EXIST:

See if an existing NDF is associated with a parameter.

NDF_PROP:

Propagate NDF information to create a new NDF via the parameter system.

Message —

NDF_CMSG:

Assign the value of an NDF character component to a message token.

NDF_MSG:

Assign the name of an NDF to a message token.

Accessing existing NDFs —

NDF_ASSOC:

Associate an existing NDF with a parameter.

NDF_EXIST:

See if an existing NDF is associated with a parameter.

NDF_FIND:

Find an NDF in an HDS structure and import it into the NDF system.

NDF_IMPRT:

Import an NDF into the NDF system from HDS.

Inquiring NDF attributes —

NDF_BOUND:

Inquire the pixel-index bounds of an NDF.

NDF_DIM:

Inquire the dimension sizes of an NDF.

NDF_ISACC:

Determine whether a specified type of NDF access is available.

NDF_ISBAS:

Inquire if an NDF is a base NDF.

NDF_ISTMP:

Determine if an NDF is temporary.

NDF_NBLOC:

Determine the number of blocks of adjacent pixels in an NDF.

NDF_NCHNK:

Determine the number of chunks of contiguous pixels in an NDF.

NDF_SAME:

Inquire if two NDFs are part of the same base NDF.

NDF_SIZE:

Determine the size of an NDF.

NDF_VALID:

Determine whether an NDF identifier is valid.

Inquiring component attributes —

NDF_BAD:

Determine if an NDF array component may contain bad pixels.

NDF_BB:

Obtain the bad-bits mask value for the quality component of an NDF.

NDF_CLEN:

Determine the length of an NDF character component.

NDF_CMPLX:

Determine whether an NDF array component holds complex values.

NDF_FORM:

Obtain the storage form of an NDF array component.

NDF_FTYPE:

Obtain the full data type of an NDF array component.

NDF_QMF:

Obtain the value of an NDF’s quality masking flag.

NDF_STATE:

Determine the state of an NDF component (defined or undefined).

NDF_TYPE:

Obtain the numeric data type of an NDF array component.

Creating and deleting NDFs —

NDF_CREAT:

Create a new simple NDF via the parameter system.

NDF_CREP:

Create a new primitive NDF via the parameter system.

NDF_DELET:

Delete an NDF.

NDF_NEW:

Create a new simple NDF.

NDF_NEWP:

Create a new primitive NDF.

NDF_PROP:

Propagate NDF information to create a new NDF via the parameter system.

Setting NDF attributes —

NDF_NOACC:

Disable a specified type of access to an NDF.

NDF_SBND:

Set new pixel-index bounds for an NDF.

NDF_SHIFT:

Apply pixel-index shifts to an NDF.

Setting component attributes —

NDF_RESET:

Reset an NDF component to an undefined state.

NDF_SBAD:

Set the bad-pixel flag for an NDF array component.

NDF_SBB:

Set a bad-bits mask value for the quality component of an NDF.

NDF_SQMF:

Set a new logical value for an NDF’s quality masking flag.

NDF_STYPE:

Set a new type for an NDF array component.

Accessing component values —

NDF_CGET:

Obtain the value of an NDF character component.

NDF_CPUT:

Assign a value to an NDF character component.

NDF_MAP:

Obtain mapped access to an array component of an NDF.

NDF_MAPQL:

Map the quality component of an NDF as an array of logical values.

NDF_MAPZ:

Obtain complex mapped access to an array component of an NDF.

NDF_QMASK:

Combine an NDF quality value with a bad-bits mask to give a logical result.

NDF_UNMAP:

Unmap an NDF or a mapped NDF array.

Inquiring and setting axis attributes —

NDF_ACLEN:

Determine the length of an NDF axis character component.

NDF_ACRE:

Ensure that an axis coordinate system exists for an NDF.

NDF_AFORM:

Obtain the storage form of an NDF axis array.

NDF_ANORM:

Obtain the logical value of an NDF axis normalisation flag.

NDF_AREST:

Reset an NDF axis component to an undefined state.

NDF_ASNRM:

Set a new value for an NDF axis normalisation flag.

NDF_ASTAT:

Determine the state of an NDF axis component (defined or undefined).

NDF_ASTYP:

Set a new numeric type for an NDF axis array.

NDF_ATYPE:

Obtain the numeric type of an NDF axis array.

Accessing axis values —

NDF_ACGET:

Obtain the value of an NDF axis character component.

NDF_ACMSG:

Assign the value of an NDF axis character component to a message token.

NDF_ACPUT:

Assign a value to an NDF axis character component.

NDF_AMAP:

Obtain mapped access to an NDF axis array.

NDF_AUNMP:

Unmap an NDF axis array component.

Creating and controlling identifiers —

NDF_ANNUL:

Annul an NDF identifier.

NDF_BASE:

Obtain an identifier for a base NDF.

NDF_BEGIN:

Begin a new NDF context.

NDF_CLONE:

Clone an NDF identifier.

NDF_END:

End the current NDF context.

NDF_VALID:

Determine whether an NDF identifier is valid.

Handling NDF (and Array) sections —

NDF_BASE:

Obtain an identifier for a base NDF.

NDF_BLOCK:

Obtain an NDF section containing a block of adjacent pixels.

NDF_CHUNK:

Obtain an NDF section containing a chunk of contiguous pixels.

NDF_NBLOC:

Determine the number of blocks of adjacent pixels in an NDF.

NDF_NCHNK:

Determine the number of chunks of contiguous pixels in an NDF.

NDF_SECT:

Create an NDF section.

NDF_SSARY:

Create an array section, using an NDF section as a template.

NDF_XIARY:

Obtain access to an array stored in an NDF extension.

Matching and merging attributes —

NDF_MBAD:

Merge the bad-pixel flags of the array components of a pair of NDFs.

NDF_MBADN:

Merge the bad-pixel flags of the array components of a number of NDFs.

NDF_MBND:

Match the pixel-index bounds of a pair of NDFs.

NDF_MBNDN:

Match the pixel-index bounds of a number of NDFs.

NDF_MTYPE:

Match the types of the array components of a pair of NDFs.

NDF_MTYPN:

Match the types of the array components of a number of NDFs.

Creating placeholders —

NDF_PLACE:

Obtain an NDF placeholder.

NDF_TEMP:

Obtain a placeholder for a temporary NDF.

Copying NDFs —

NDF_COPY:

Copy an NDF to a new location.

NDF_PROP:

Propagate NDF information to create a new NDF via the parameter system.

Handling extensions —

NDF_XDEL:

Delete a specified NDF extension.

NDF_XGT0t:

Read a scalar value from a component within a named NDF extension.

NDF_XIARY:

Obtain access to an array stored in an NDF extension.

NDF_XLOC:

Obtain access to a named NDF extension via an HDS locator.

NDF_XNAME:

Obtain the name of the Nth extension in an NDF.

NDF_XNEW:

Create a new extension in an NDF.

NDF_XNUMB:

Determine the number of extensions in an NDF.

NDF_XPT0t:

Write a scalar value to a component within a named NDF extension.

NDF_XSTAT:

Determine if a named NDF extension exists.

Tuning —

NDF_GTUNE:

Obtain the value of an NDF system tuning parameter.

NDF_TRACE:

Set the internal NDF system error-tracing flag.

NDF_TUNE:

Set an NDF system tuning parameter.

21.2.2 ARY — ARRAY data structure access

[SUN/11]

Message —

ARY_MSG:

Assign the name of an array to a message token.

Accessing existing arrays —

ARY_FIND:

Find an array in an HDS structure and import it into the ARY system.

ARY_IMPRT:

Import an array into the ARY system from HDS.

Inquiring array attributes —

ARY_BAD:

Determine if an array may contain bad pixels.

ARY_BOUND:

Inquire the pixel-index bounds of an array.

ARY_CMPLX:

Determine whether an array holds complex values.

ARY_DIM:

Inquire the dimension sizes of an array.

ARY_FORM:

Obtain the storage form of an array.

ARY_FTYPE:

Obtain the full data type of an array.

ARY_ISACC:

Determine whether a specified type of array access is available.

ARY_ISMAP:

Determine if an array is currently mapped.

ARY_ISBAS:

Inquire if an array is a base array.

ARY_ISTMP:

Determine if an array is temporary.

ARY_NDIM:

Inquire the dimensionality of an array.

ARY_OFFS:

Obtain the pixel offset between two arrays.

ARY_SAME:

Inquire if two arrays are part of the same base array.

ARY_SIZE:

Determine the size of an array.

ARY_STATE:

Determine the state of an array (defined or undefined).

ARY_TYPE:

Obtain the numeric type of an array.

ARY_VALID:

Determine whether an array identifier is valid.

ARY_VERFY:

Verify that an array’s data structure is correctly constructed.

Creating and deleting arrays —

ARY_DELET:

Delete an array.

ARY_DUPE:

Duplicate an array.

ARY_NEW:

Create a new simple array.

ARY_NEWP:

Create a new primitive array.

Setting array attributes —

ARY_NOACC:

Disable a specified type of access to an array.

ARY_RESET:

Reset an array to an undefined state.

ARY_SBAD:

Set the bad-pixel flag for an array.

ARY_SHIFT:

Apply pixel-index shifts to an array.

ARY_STYPE:

Set a new type for an array.

Accessing array values —

ARY_MAP:

Obtain mapped access to an array.

ARY_MAPZ:

Obtain complex mapped access to an array.

ARY_UNMAP:

Unmap an array.

Creating and controlling identifiers —

ARY_ANNUL:

Annul an array identifier.

ARY_BASE:

Obtain an identifier for a base array.

ARY_CLONE:

Clone an array identifier.

ARY_SECT:

Create an array section.

ARY_SSECT:

Produce a similar array section to an existing one.

ARY_VALID:

Determine whether an array identifier is valid.

Creating placeholders —

ARY_PLACE:

Obtain a placeholder for an array.

ARY_TEMP:

Obtain a placeholder for a temporary array.

Copying arrays —

ARY_COPY:

Copy an array to a new location.

ARY_DUPE:

Duplicate an array.

Miscellaneous —

ARY_TRACE:

Set the internal ARY system error-tracing flag.

21.2.3 REF — References to HDS objects

[SUN/31]

21.2.4 HDS — Hierarchical data system

[SUN/92]

In the following lists of routine names, routines which belong to a related set are shown on a single line with ‘d’ standing for various dimensionalities, and ‘t’ standing for various data types. Not all possible combinations may be available; please refer to SUN/92 for an explicit list. HDS routines: 

Inquiry —

CMP_LEN:

Inquire component precision.

CMP_PRIM:

Inquire component primitive.

CMP_SHAPE:

Inquire component shape.

CMP_SIZE:

Inquire component size.

CMP_STRUC:

Inquire component structure.

CMP_TYPE:

Inquire component type.

Basic I/O —

CMP_GETdt:

Read component.

CMP_PUTdt:

Write component.

CMP_MAPd:

Map component.

CMP_UNMAP:

Unmap component.

CMP_MODt:

Obtain component.

Parameter —

DAT_ASSOC:

Associate a data object with a parameter.

DAT_EXIST:

Same as DAT_ASSOC except if there is an error it returns a status value, whereas DAT_ASSOC repeatedly attempts to get a valid locator.

DAT_CANCL:

Cancel the association between a data object and a parameter.

DAT_CREAT:

Create a data structure component.

DAT_DEF:

Suggest values for a parameter.

DAT_DELET:

Delete an object associated with a parameter.

DAT_UPDAT:

Force HDS update from memory cache.

Inquiry —

DAT_NAME:

Inquire object name.

DAT_REF:

Inquire object reference name.

DAT_PRIM:

Inquire object primitive.

DAT_SHAPE:

Inquire object shape.

DAT_SIZE:

Inquire object size.

DAT_STATE:

Inquire object state.

DAT_STRUC:

Inquire object structure.

DAT_TYPE:

Inquire object type.

DAT_WHERE:

Inquire primitive data in file.

DAT_LEN:

Inquire primitive precision.

DAT_PREC:

Inquire storage precision.

DAT_DREP:

Inquire primitive data representation information.

DAT_CLEN:

Inquire character string length.

DAT_NCOMP:

Inquire number of components.

DAT_THERE:

Inquire component existence.

DAT_VALID:

Inquire locator valid.

Basic I/O —

DAT_GETdt:

Read primitive object.

DAT_PUTdt:

Write primitive object.

DAT_MAPt:

Map primitive object.

DAT_BASIC:

Map primitive object as a sequence of bytes.

DAT_UNMAP:

Unmap primitive object.

Other (sorted by description) —

DAT_ALTER:

Alter object size.

DAT_MOULD:

Alter object shape.

DAT_ANNUL:

Annul locator.

DAT_MSG:

Assign object name to message token.

DAT_RETYP:

Change object type.

DAT_CLONE:

Clone locator.

DAT_COERC:

Coerce object shape.

DAT_CCOPY:

Copy one structure level.

DAT_COPY:

Copy object.

DAT_CCTYP:

Create type string.

DAT_NEWdt:

Create component.

DAT_TEMP:

Create temporary object.

DAT_ERASE:

Erase component.

DAT_FIND:

Find named component.

DAT_PAREN:

Find parent.

DAT_INDEX:

Index into component list.

DAT_CELL:

Locate cell.

DAT_SLICE:

Locate slice.

DAT_MOVE:

Move object.

DAT_RENAM:

Rename object.

DAT_RESET:

Reset object state.

DAT_ERMSG:

Translate error status.

DAT_VEC:

Vectorise object.

• XXX stand for CMP, DAT, and EXC routines.
• xxx stand for HDS routines.

21.3 Message and Error systems

21.3.1 MSG/ERR — Message and Error reporting

[SUN/104] MSG routines: 

21.4 Graphics system

21.4.1 NCAR/SNX — Graphics utilities

[SUN/88, SUN/90]

Currently there are no NCAR ‘parameter routines’. A full list of ‘stand-alone’ NCAR routine names is given in SUN/88. The routines are implemented within groupings called utilities which have the following names:

SNX routines: 

Functions —

SNX_AGGUX:

Transform grid X coordinate to user X coordinate.

SNX_AGGUY:

Transform grid Y coordinate to user Y coordinate.

SNX_AGUGX:

Transform user X coordinate to grid X coordinate.

SNX_AGUGY:

Transform user Y coordinate to grid Y coordinate.

Subroutines —

SNX_AGOP:

Make AUTOGRAPH/SGS/GKS ready for plotting.

SNX_EZRXY:

Plot x,y data, with labelling, using AUTOGRAPH.

SNX_AGLAB:

Set up an AUTOGRAPH label.

SNX_CHSET:

Select one of the two NCAR Roman fonts.

SNX_AGSAV:

Save the state of AUTOGRAPH.

SNX_AGRES:

Restore the state of AUTOGRAPH.

SNX_TO:

Switch between NCAR and SGS plotting.

SNX_AGWV:

Make the AUTOGRAPH graph window match the current viewport ($=$ zone if using SGS).

SNX_AGCS:

Make the current SGS zone world coordinates match the AUTOGRAPH grid coordinate system.

SNX_CURS:

Read a cursor position.

SNX_WRTST:

Plot a character string.

21.4.2 PGPLOT — Graphics library

[SUN/15]

Control —

PGADVANCE:

See PGPAGE.

PGASK:

Control new page prompting.

PGBBUF:

Begin batch of output (buffer).

PGBEGIN:

Begin PGPLOT, open output device.

PGEBUF:

End batch of output (buffer).

PGEND:

Terminate PGPLOT.

PGPAGE:

Advance to a new page or clear screen.

PGPAPER:

Change the size of the view surface.

PGUPDT:

Update display.

Windows and viewports —

PGBOX:

Draw labeled frame around viewport.

PGENV:

Set window and viewport and draw labeled frame.

PGVPORT:

Set viewport (normalized device coordinates).

PGVSIZE:

Set viewport (inches).

PGVSTAND:

Set standard (default) viewport.

PGWINDOW:

Set window.

PGWNAD:

Set window and adjust viewport to same aspect ratio.

Primitive drawing —

PGDRAW:

Draw a line from the current pen position to a point.

PGLINE:

Draw a polyline.

PGMOVE:

Move pen.

PGPOINT:

Draw one or more graph markers.

PGPOLY:

Fill a polygonal area with shading.

PGRECT:

Draw a rectangle, using fill-area attributes.

Text —

PGLABEL:

Write labels for x-axis, y-axis, and top of plot.

PGMTEXT:

Write text at position relative to viewport.

PGPTEXT:

Write text at arbitrary position and angle.

PGTEXT:

Write text (horizontal, left-justified).

Attribute setting —

PGSCF:

Set character font.

PGSCH:

Set character height.

PGSCI:

Set color index.

PGSCR:

Set color representation.

PGSFS:

Set fill-area style.

PGSHLS:

Set color representation using HLS system.

PGSLS:

Set line style.

PGSLW:

Set line width.

Higher-level drawing —

PGBIN:

Histogram of binned data.

PGCONS:

Contour map of a 2-d data array (fast algorithm).

PGCONT:

Contour map of a 2-d data array (contour-following).

PGCONX:

Contour map of a 2-d data array (non-rectangular).

PGERRX:

Horizontal error bar.

PGERRY:

Vertical error bar.

PGFUNT:

Function defined by X = F(T), Y = G(T).

PGFUNX:

Function defined by Y = F(X).

PGFUNY:

Function defined by X = F(Y).

PGGRAY:

Gray-scale map of a 2-d data array.

PGHI2D:

Cross-sections through a 2-d data array.

PGHIST:

Histogram of unbinned data.

Interactive graphics (cursor) —

PGCURSE:

Read cursor position.

PGLCUR:

Draw a line using the cursor.

PGNCURSE:

Mark a set of points using the cursor.

PGOLIN:

Mark a set of points using the cursor.

Inquiry —

PGQCF:

Inquire character font.

PGQCH:

Inquire character height.

PGQCI:

Inquire color index.

PGQCR:

Inquire color representation.

PGQFS:

Inquire fill-area style.

PGQINF:

Inquire general information.

PGQLS:

Inquire line style.

PGQLW:

Inquire line width.

PGQVP:

Inquire viewport size and position.

PGQWIN:

Inquire window boundary coordinates.

Utilities —

PGETXT:

Erase text from graphics display.

PGIDEN:

Write username, date, and time at bottom of plot.

PGLDEV:

List available device types.

PGNUMB:

Convert a number into a plottable character string.

PGRND:

Find the smallest “round” number greater than x.

PGRNGE:

Choose axis limits.

21.4.3 NAG — Graphics library

[SUN/29]

Axes, Grids, Borders, and Titles —

J06AAF:

Pair of axes for current data region, automatic annotation.

J06ABF:

Pair of axes for current data region, user-specified annotation.

J06ACF:

Grid for the current data region, automatic annotation.

J06ADF:

Grid for the current data region, user-specifiable annotation.

J06AEF:

Scaled border for current data region, automatic annotation.

J06AFF:

Scaled border for current data region, user-specified annotation.

J06AGF:

Single axis under user control.

J06AHF:

Plot title, centred at the top of the current data region.

J06AJF:

Axis title, centred at side or bottom of current data region.

J06AKF:

Pair of logarithmic axes for current data region, automatic annotation.

J06ALF:

Logarithmic grid for current data region, automatic annotation.

J06AMF:

Logarithmic border for current data region, automatic annotation.

J06ANF:

Single logarithmic axis under user control.

J06APF:

Single axis with user-specified position of tick marks and annotation.

J06AQF:

Single axis with user-supplied annotation, and control over position of tick marks and annotation.

Point plotting and Straight line drawing —

J06BAF:

Plot data points with optional straight lines and markers.

J06BBF:

Linear regression line using output from G02CAF, G02CBF, G02CCF or G02CDF.

J06BCF:

Plot a series of data points with optional error bars.

J06BYF:

Key to current NAG pen styles.

J06BZF:

Key to current line styles and/or markers.

Curve drawing —

J06CAF:

Plot single-valued curve through data points.

J06CBF:

Plot single-valued curve through data points, called point-wise.

J06CCF:

Plot possibly multi-valued curve through data points.

J06CDF:

Plot possibly multi-valued curve through data points, called point-wise.

ODE graphics —

J06DAF:

Plot a graph of components of the solution of a system of ODEs, comprehensive version, using option setting.

General function drawing —

J06EAF:

Plot user-supplied function over specified range.

J06EBF:

Plot user-supplied function over specified range, called point-wise.

J06ECF:

Plot a parametric curve.

Special function drawing —

J06FAF:

Plot cubic spline in an interval, from its B-spline representation.

J06FBF:

Plot polynomial represented in Chebyshev form, using output from E02ADF or E02AFF.

Contouring —

J06GAF:

Easy-to-use contour map, data on regular rectangular grid.

J06GBF:

Comprehensive contour map, data on regular rectangular grid.

J06GCF:

Easy-to-use contour map, data on irregular rectangular grid.

J06GDF:

Comprehensive contour map, data on irregular rectangular grid.

J06GEF:

Easy-to-use contour map, user-supplied function.

J06GFF:

Comprehensive contour map, user-supplied function.

J06GGF:

Comprehensive contour map, using option setting, data scattered.

J06GYF:

Key to contour plot produced with J06GGF.

J06GZF:

Key to contour indices.

Surface viewing —

J06HAF:

Easy-to-use isometric surface view, data on regular rectangular grid.

J06HBF:

Comprehensive isometric surface view, data on regular rectangular grid.

J06HCF:

Perspective surface view, data on regular rectangular grid.

J06HDF:

Easy-to-use perspective surface view, data on irregular rectangular grid.

J06HEF:

Comprehensive perspective surface view, data on irregular rectangular grid.

J06HFF:

Perspective surface view, sections parallel to either horizontal axis.

J06HGF:

Perspective view of a 3-d histogram.

J06HHF:

Annotate data points on a perspective surface view.

J06HJF:

Annotate individual data blocks on a 3-d histogram.

J06HKF:

Isometric surface view of a 2-d function f(x,y).

J06HLF:

Perspective surface view of a 2-d function f(x,y).

Data presentation —

J06JAF:

Shaded bar chart, vertical, various styles (easy-to-use).

J06JBF:

Shaded bar chart, vertical, various styles (comprehensive).

J06JCF:

Shaded bar chart, variable width bars.

J06JDF:

Shaded bar chart, horizontal, various styles (easy-to-use).

J06JEF:

Shaded bar chart, horizontal, various styles (comprehensive).

J06JFF:

Shaded block chart, variable width and height blocks.

J06JGF:

Marker diagram, sorts data into bins.

J06JHF:

Marker diagram, subdivision of bins.

J06JKF:

Shaded pie chart, (easy-to-use).

J06JLF:

Shaded pie chart, (comprehensive).

J06JMF:

Shaded bar chart, vertical or horizontal, no subdivision of bins (easy-to-use).

J06JNF:

Frequency distribution diagram, various styles, integer grid input.

J06JPF:

Frequency distribution diagram and scatter plot, various styles, x,y input data.

J06JYF:

Key to numeric values.

J06JZF:

Key to area fill styles.

Vector field plotting —

J06KAF:

Plot a 2-d vector field diagram.

J06KBF:

Plot a 3-d vector field diagram.

J06KCF:

Plot a 2-d vector field diagram from a user-supplied function.

J06KDF:

Plot a 3-d vector field diagram from a user-supplied function.

Statistical graphics —

J06SAF:

Plot a time-series, and optionally user-supplied forecasts and standard error limits.

J06SBF:

Plot autocorrelation or partial autocorrelation function of a time series.

J06SCF:

Plot a cumulative normal probability graph. Data may be grouped together and a histogram plotted.

J06SDF:

Plot a linear regression line and optional confidence limits for data and line.

J06SEF:

Draw box and whisker plots.

I/O utilities —

J06VAF:

Return or define the unit number for error messages.

J06VBF:

Return or define the unit number for advisory messages.

J06VCF:

Return or define the unit number for command sequence output.

J06VDF:

Return or define the unit number from which Hershey fonts will be read (used only by PC Graphics implementations).

J06VEF:

Return or define the unit number to which SAVE options should be directed.

J06VFF:

Read a set of optional parameters from an external file.

J06VGF:

Supply individual optional parameter for a specified routine.

21.4.4 SGS — Simple graphics system

[SUN/85]

Parameter —

SGS_ASSOC:

Associate an SGS zone with a parameter.

SGS_CANCL:

Cancel the association of an SGS zone with a parameter.

SGS_ANNUL:

Release an SGS zone and annul its descriptor.

Control —

SGS_OPEN:

Open SGS & GKS, opening and activating one workstation.

SGS_INIT:

Open SGS & GKS, without opening a workstation.

SGS_CLOSE:

Shut down SGS & GKS.

SGS_OPNWK:

Open a new workstation and select it.

SGS_CLSWK:

Close a workstation.

SGS_WLIST:

Output a list of available workstations.

SGS_SPEN:

Select a pen for line and text drawing.

SGS_IPEN:

Inquire current pen number.

SGS_FLUSH:

Complete all pending output.

SGS_ISLER:

Inquire whether device has selective erase capability.

SGS_CLRFG:

Set or clear the ‘clear display on open’ flag.

Zones —

SGS_ZONE:

Create and select a zone of the specified extent.

SGS_ZSHAP:

Create and select a zone of the specified aspect ratio.

SGS_ZSIZE:

Create and select a zone of the specified size.

SGS_ZPART:

Partition current zone into NX by NY pieces.

SGS_SW:

Set window of current zone to given bounds.

SGS_SELZ:

Select another zone.

SGS_RELZ:

Release the specified zone.

SGS_CLRZ:

Clear the current zone (even if this means clearing the whole display surface).

SGS_ICURZ:

Inquire ID of current zone.

SGS_IZONE:

Inquire window bounds and size on the display surface for the current zone.

SGS_IDUN:

Inquire the plotting resolution of the current zone.

SGS_TPZ:

Transform position from one zone to another.

SGS_BZNDC:

Set the NDC extent of a base zone.

Plotting lines —

SGS_BPOLY:

Begin a new polyline.

SGS_APOLY:

Append a new line to the polyline.

SGS_OPOLY:

Output the polyline.

SGS_IPLXY:

Inquire end of current polyline.

SGS_LINE:

Begin a new polyline with a single line.

SGS_BOX:

Draw a rectangle.

SGS_CIRCL:

Draw a circle.

SGS_ARC:

Draw an arc of a circle.

SGS_CLRBL:

Clear a rectangular area (if this can be done without affecting the rest of the display surface).

Plotting text —

SGS_BTEXT:

Begin a new text string.

SGS_ATEXT:

Append text to the current string.

SGS_OTEXT:

Output the text string.

SGS_ATXI:

Format an integer onto the current text string.

SGS_ATXR:

Format a real number onto the current text string.

SGS_ATXL:

Append text to the current text string, omitting trailing blanks.

SGS_ATXB:

Append right justified field to the current text string.

SGS_TX:

Begin a new text string with a string.

SGS_TXI:

Begin a new text string with a formatted integer.

SGS_TXR:

Begin a new text string with a formatted real number.

SGS_ITXB:

Inquire status of current text string.

Plotting markers —

SGS_MARK:

Draw a single marker.

SGS_MARKL:

Draw a marker at current end of polyline.

Attributes of characters —

SGS_SFONT:

Select text font.

SGS_SPREC:

Specify text precision.

SGS_SHTX:

Specify character height.

SGS_SARTX:

Specify text aspect ratio.

SGS_SUPTX:

Specify character orientation.

SGS_SSPTX:

Specify character spacing.

SGS_STXJ:

Specify text alignment.

SGS_ITXA:

Inquire text attributes.

Input —

SGS_CUVIS:

Set visibility of cursor.

SGS_DEFCH:

Define valid choice keys.

SGS_DISCU:

Disable sample mode for cursor.

SGS_ENSCU:

Enable sample mode for cursor.

SGS_ICUAV:

Inquire cursor availability.

SGS_INCHO:

Inquire number of choices.

SGS_REQCH:

Request choice.

SGS_REQCU:

Request cursor position.

SGS_SAMCU:

Sample cursor position.

SGS_SELCH:

Select choice device.

SGS_SETCU:

Set cursor position.

GKS Inquires —

SGS_ICURW:

Inquire workstation ID for the current zone.

SGS_WIDEN:

Translate workstation name to GKS type and connection ID.

SGS_WNAME:

Get list of workstation names.

21.4.5 GKS — Graphical kernel system

[SUN/83]

The GKS routines should not be used in ADAM programs, except in special cases, so they will not be listed here. A full list of the stand-alone routines is available in the RAL GKS Guide, in addition to which there exist the following ‘parameter routines’:

21.4.6 IDI — Image display interface

[SUN/65]

Parameter —

IDI_ASSOC:

Associate a display device with a parameter.

IDI_CANCL:

Cancel the association of a display device with a parameter.

IDI_ANNUL:

Release a display device and annul its descriptor.

Control —

IIDOPN:

Open display.

IIDCLO:

Close display.

IIDRST:

Reset display.

IIDUPD:

Update display.

IIDERR:

Get error.

Configuration —

IIDQDV:

Query device characteristics.

IIDQCI:

Query capabilities integer.

IIDQCR:

Query capabilities real.

IIDQDC:

Query defined configuration.

IIDSEL:

Select configuration.

Memories —

IIMSMV:

Set memory visibility.

IIZWSC:

Write memory scroll.

IIZWZM:

Write memory zoom.

IIZRSZ:

Read memory scroll and zoom.

IIMSLT:

Select memory look-up tables.

IIMSDP:

Select display path.

IIMWMY:

Write memory.

IIMCMY:

Clear memory.

IIMRMY:

Read memory.

IIMSTW:

Set transfer window.

Graphics —

IIGPLY:

Draw polyline.

IIGTXT:

Plot text.

Look-up table —

IILWIT:

Write intensity transformation table.

IILRIT:

Read intensity transformation table.

IILWLT:

Write video look-up tables.

IILRLT:

Read video look-up tables.

Zoom and Pan —

IIZWZP:

Write display zoom and pan.

IIZRZP:

Read display zoom and pan.

Cursor —

IICINC:

Initialize cursor.

IICSCV:

Set cursor visibility.

IICRCP:

Read cursor position.

IICWCP:

Write cursor position.

Region of interest —

IIRINR:

Initialize rectangular region of interest.

IIRSRV:

Set visibility rectangular region of interest.

IIRRRI:

Read rectangular region of interest.

IIRWRI:

Write rectangular region of interest.

Interaction —

IIIENI:

Enable interaction.

IIIEIW:

Execute interaction and wait.

IIISTI:

Stop interactive input.

IIIQID:

Query interactor description.

IIIGLD:

Get locator displacement.

IIIGIE:

Get integer evaluator.

IIIGRE:

Get real evaluator.

IIIGLE:

Get logical evaluator.

IIIGSE:

Get string evaluator.

Miscellaneous —

IIDSNP:

Create snapshot.

IIMBLM:

Blink memories.

IIDSSS:

Set split screen.

IILSBV:

Set intensity bar visibility.

IIDIAG:

Diagnostic routine.

IIEGEP:

Get escape parameter.

IIEPEP:

Put escape parameter.

Workstation interface —

IIDENC:

Enable configuration.

IIDAMY:

Allocate memory.

IIDSTC:

Stop configuration.

IIDRLC:

Release configuration.

Additional —

IDI_CLRFG:

Set clear flag.

21.4.7 AGI — Applications graphics interface

[SUN/48]

Parameter —

AGI_ASSOC:

Associate a workstation with a parameter.

AGI_CANCL:

Cancel parameter association.

AGI_ANNUL:

Annul the picture identifier.

Control —

AGI_BEGIN:

Mark the beginning of a new AGI scope.

AGI_CLOSE:

Close AGI in a non-ADAM environment.

AGI_END:

Mark the end of an AGI scope.

AGI_NUPIC:

Create a new picture in the database.

AGI_OPEN:

Open AGI in a non-ADAM environment.

AGI_PDEL:

Delete all pictures on a workstation.

AGI_SELP:

Select the given picture as the current one.

AGI_SROOT:

Select the root picture for searching.

Inquiries —

AGI_IBASE:

Inquire base picture for current workstation.

AGI_ICOM:

Inquire comment for current picture.

AGI_ICURP:

Inquire current picture identifier.

AGI_INAME:

Inquire name of current picture.

AGI_IPOBS:

Inquire if current picture obscured by another.

AGI_ISAMD:

Inquire if pictures are on same device.

AGI_ITOBS:

Inquire if test points are obscured.

AGI_IWOCO:

Inquire world coordinates of current picture.

Recall —

AGI_RCF:

Recall first picture of specified name.

AGI_RCFP:

Recall first picture embracing a position.

AGI_RCL:

Recall last picture of specified name.

AGI_RCLP:

Recall last picture embracing a position.

AGI_RCP:

Recall preceding picture of specified name.

AGI_RCPP:

Recall preceding picture embracing a position.

AGI_RCS:

Recall succeeding picture of specified name.

AGI_RCSP:

Recall succeeding picture embracing a position.

Labels —

AGI_ILAB:

Inquire label of a picture.

AGI_SLAB:

Store label in picture.

Reference —

AGI_GTREF:

Get a reference to an HDS object.

AGI_PTREF:

Write a reference to an HDS object.

Transformations —

AGI_TDDTW:

Transform double precision data to world coordinates.

AGI_TDTOW:

Transform data to world coordinates.

AGI_TNEW:

Store a transformation in the database.

AGI_TWTDD:

Transform double precision world to data coordinates.

AGI_TWTOD:

Transform world to data coordinates.

Interface to IDI —

AGD_ACTIV:

Initialise IDI.

AGD_DEACT:

Close down IDI.

AGD_NWIND:

Define an IDI window from the current picture.

AGD_SWIND:

Save an IDI window in the database.

Interface to PGPLOT —

AGP_ACTIV:

Initialise PGPLOT.

AGP_DEACT:

Close down PGPLOT.

AGP_NVIEW:

Create a new viewport from the current picture.

AGP_SVIEW:

Save the current viewport in the database.

Interface to SGS —

AGS_ACTIV:

Initialise SGS.

AGS_DEACT:

Close down SGS.

AGS_NZONE:

Create a new zone from the current picture.

AGS_SZONE:

Save the current zone in the database.

21.4.8 GNS — Graphics workstation name service

[SUN/57]

Get names —

GNS_GTN:

Get terminal name.

GNS_GWNG:

Get next GKS workstation name.

GNS_GWNI:

Get next IDI workstation name.

Inquiries —

GNS_IANG:

Inquire AGI name of GKS workstation.

GNS_IANI:

Inquire AGI name of IDI workstation.

GNS_IDNG:

Inquire device name of GKS workstation.

GNS_IETG:

Inquire string to erase text screen.

GNS_IGAG:

Inquire GKS workstation name from AGI name.

GNS_IIAI:

Inquire IDI workstation name from AGI name.

GNS_ITWCG:

Inquire a workstation characteristic from its type.

GNS_IWCG:

Inquire a workstation characteristic.

GNS_IWSG:

Inquire workstation scale.

Control —

GNS_START:

Start the GNS system for the specified package.

GNS_STOP:

Stop the GNS system for the specified package.

Translation —

GNS_TNDG:

Translate a name and device to a GKS device specification.

GNS_TNG:

Translate a name to a GKS device specification.

GNS_TNI:

Translate a name to a IDI device specification.

21.5 Input/output systems

21.5.1 FIO/RIO — File I/O

[SUN/143] FIO routines: 

Parameter —

FIO_ASSOC:

Associate a parameter with a sequential file.

FIO_CANCL:

Cancel the association between a parameter and a sequential file.

File management and positioning —

FIO_OPEN:

Create and open a sequential file.

FIO_CLOSE:

Close a sequential file.

FIO_RWIND:

Rewind a sequential file.

FIO_ERASE:

Delete a sequential file.

FIO_SERR:

Set error status.

FIO_DEACT:

Deactivate FIO.

FIO_STOP:

Close down FIO.

File information and Fortran unit numbers —

FIO_FNAME:

Get a file’s full name.

FIO_UNIT:

Get a file’s Fortran unit number.

FIO_GUNIT:

Get an unused Fortran unit number.

FIO_PUNIT:

Release a Fortran unit number.

I/O —

FIO_READ:

Read a sequential record.

FIO_READF:

Fast read a sequential record.

FIO_WRITE:

Write a sequential record.

Parameter —

RIO_ASSOC:

Associate a parameter with a direct-access file.

RIO_CANCL:

Cancel the association between a direct-access file and a parameter.

File management —

RIO_OPEN:

Open a direct-access file.

RIO_ERASE:

Delete a direct-access file.

I/O —

RIO_READ:

Read a direct-access record.

RIO_WRITE:

Write a direct-access record.

21.5.2 MAG — Magnetic tape I/O

[APN/1]

Parameter —

MAG_ASSOC:

Associate a parameter with a tape drive.

MAG_CANCL:

Cancel the association between a parameter and a tape drive.

MAG_ANNUL:

Annul a tape descriptor.

Device management —

MAG_ALOC:

Allocate a tape drive.

MAG_DEAL:

De-allocate a tape drive.

MAG_MOUNT:

Mount a tape on a drive.

MAG_DISM:

Dismount a tape on a drive.

Tape positioning —

MAG_JUMP:

Skip blocks.

MAG_SKIP:

Skip files.

MAG_JEOV:

Skip past an EOV marker.

MAG_REW:

Position a tape at its beginning.

MAG_MOVE:

Position a tape at an absolute position.

MAG_POS:

Obtain an absolute position.

MAG_SET:

Set an absolute position.

I/O —

MAG_READ:

Read a block from a tape.

MAG_WRITE:

Write a block to a tape.

MAG_WTM:

Write a tape mark to a tape.

21.6 Database system

21.6.1 CHI — Catalogue handling

[SUN/119]

Control —

CHI_OPEN:

Activate the interface.

CHI_CLOSE:

Deactivate the interface.

List catalogues —

CHI_AVAILCATS:

Get a list of currently available catalogues.

Manipulate data —

CHI_GETNUMENTS:

Get the number of entries in a catalogue.

CHI_GETP:

Get the parameter names and the number of parameters.

CHI_GETF:

Get the field names and the number of fields.

CHI_GETFINF:

Get information associated with a field.

CHI_GETPINF:

Get information associated with a parameter.

CHI_ADDP:

Add a parameter to a catalogue.

CHI_DELP:

Delete a parameter from a catalogue.

Create catalogues —

CHI_NOENT:

Create a new catalogue with no entries.

CHI_CREATDUP:

Create a duplicate catalogue with no entries.

CHI_SELFLDS:

Create a new catalogue with fields selected from an existing catalogue.

CHI_SEARCH:

Create a new catalogue with entries selected from an existing catalogue.

CHI_REJECT:

Similar to CHI_SEARCH but with entries that fail selection criteria.

CHI_JOIN:

Create a new catalogue by joining two existing catalogues based on join criteria.

CHI_MERGE:

Create a new catalogue by merging two existing catalogues.

CHI_NEWFLD:

Create a new catalogue by adding a new field to an existing catalogue.

Delete catalogues —

CHI_DELCAT:

Delete a catalogue.

Put information into catalogues —

CHI_PUTCENT:

Put a complete entry into a catalogue.

CHI_PUTENT:

Put a set of values that constitute an entry into a catalogue.

Get information out of catalogues —

CHI_GETCENT:

Get a complete entry from a catalogue.

CHI_GETCENTPOS:

Get a complete entry from a given position in a catalogue.

CHI_GETVAL:

Get a field value(s) from the next entry in a catalogue.

CHI_GETSVALS:

Get a field value(s) for a specified number of entries in a catalogue.

21.7 Utilities

The following libraries are not specific to ADAM but, with the increased interest in writing portable code, they can be of considerable use to the writer of ADAM applications.

21.7.1 CHR — Character handling

[SUN/40]

Decoding —

CHR_CTOD:

Read a double precision number from a character string.

CHR_CTOI:

Read an integer number from a character string.

CHR_CTOL:

Read a logical value from a character string.

CHR_CTOR:

Read a real number from a character string.

CHR_DCWRD:

Returns all the words in a string.

CHR_HTOI:

Read an integer from a hex string.

CHR_OTOI:

Read an integer from an octal string.

Encoding and Formatting —

CHR_CTOC:

Write a character value into a string.

CHR_DTOC:

Encode a double precision value as a string.

CHR_ITOC:

Encode an integer value as a string.

CHR_LTOC:

Encode a logical value as a string.

CHR_RTOC:

Encode a real value as a string.

CHR_PUTC:

Copy one string into another at given position.

CHR_PUTD:

Put double precision value into string at given position.

CHR_PUTI:

Put integer value into string at given position.

CHR_PUTL:

Put logical value into string at given position

CHR_PUTR:

Put real value into string at given position.

CHR_RTOAN:

Write a real into character string as hr/deg:min:sec.

Inquiry —

CHR_DELIM:

Locate substring with given delimiter character.

CHR_EQUAL:

Determine whether two strings are equal.

CHR_FANDL:

Find the indices of the first and last non-blank characters.

CHR_FIWE:

Find next end of word.

CHR_FIWS:

Find start of next word.

CHR_INDEX:

Find the index of a substring in a string.

CHR_INSET:

Determine whether a string is a member of a set.

CHR_ISALF:

Determine whether a character is alphabetic.

CHR_ISALM:

Determine whether a character is alphanumeric.

CHR_ISDIG:

Determine whether a character is a digit.

CHR_ISNAM:

Determine whether a string is a valid name.

CHR_LEN:

Find used length of string.

CHR_SIMLR:

Determine whether two strings are equal apart from case.

CHR_SIZE:

Find the declared size of string.

String manipulation —

CHR_APPND:

Copy one string into another (ignoring trailing blanks).

CHR_CLEAN:

Remove all non-printable ASCII characters from a string.

CHR_COPY:

Copy one string to another, checking for truncation.

CHR_FILL:

Fill a string with a given character.

CHR_LCASE:

Convert a string to lower case.

CHR_LDBLK:

Remove leading blanks from a string.

CHR_LOWER:

Give lower case equivalent of a character.

CHR_MOVE:

Move one string into another (ignoring trailing blanks).

CHR_RMBLK:

Remove all blanks from a string in situ.

CHR_SWAP:

Swap two single-character variables.

CHR_TERM:

Terminate string by padding out with blanks.

CHR_TRUNC:

Truncate string rightwards from a given delimiter.

CHR_UCASE:

Convert a string to upper case.

CHR_UPPER:

Give upper case equivalent of a character.

21.7.2 CNF/F77 — Mixed language programming

[SGP/5] CNF functions:  CNF is a set of C functions to handle the difference between Fortran and C character strings.

Import a Fortran string to C —

CNF_CREIB:

Create a temporary C string and import a blank filled Fortran string into it.

CNF_CREIM:

Create a temporary C string and import a Fortran string into it.

CNF_IMPB:

Import a Fortran string into a C string, retaining trailing blanks.

CNF_IMPBN:

Import no more than max characters from a Fortran string into a C string, retaining trailing blanks.

CNF_IMPN:

Import no more than max characters from a Fortran string into a C string.

CNF_IMPRT:

Import a Fortran string into a C string.

Export a C string to Fortran —

CNF_EXPN:

Export a C string to a Fortran string, copying given a maximum number of characters.

CNF_EXPRT:

Export a C string to a Fortran string.

String lengths —

CNF_LENC:

Find the length of a C string.

CNF_LENF:

Find the length of a Fortran string.

Miscellaneous —

CNF_COPYF:

Copy one Fortran string to another Fortran string.

CNF_CREAT:

Create a temporary C string and return a pointer to it.

CNF_FREE:

Return temporary space.

Declaration of a C function —

F77_BYTE_FUNCTION:

Declare a function that returns a BYTE value.

F77_CHARACTER_FUNCTION:

Declare a function that returns a CHARACTER value.

F77_DOUBLE_FUNCTION:

Declare a function that returns a DOUBLE PRECISION value.

F77_INTEGER_FUNCTION:

Declare a function that returns an INTEGER value.

F77_LOGICAL_FUNCTION:

Declare a function that returns a LOGICAL value.

F77_REAL_FUNCTION:

Declare a function that returns a REAL value.

F77_SUBROUTINE:

Declare a SUBROUTINE.

F77_WORD_FUNCTION:

Declare a function that returns a WORD value.

Arguments of a C function —

BYTE:

Declare a BYTE argument.

BYTE_ARRAY:

Declare a BYTE array argument.

CHARACTER:

Declare a CHARACTER argument.

CHARACTER_ARRAY:

Declare a CHARACTER array argument.

CHARACTER_RETURN_VALUE:

Declare an argument that will be the return value of a CHARACTER function.

DOUBLE:

Declare a DOUBLE PRECISION argument.

DOUBLE_ARRAY:

Declare a DOUBLE PRECISION array argument.

INTEGER:

Declare an INTEGER argument.

INTEGER_ARRAY:

Declare an INTEGER array argument.

LOGICAL:

Declare a LOGICAL argument.

LOGICAL_ARRAY:

Declare a LOGICAL array argument.

POINTER:

Declare a POINTER argument.

REAL:

Declare a REAL argument.

REAL_ARRAY:

Declare a REAL array argument.

TRAIL:

Declare hidden trailing arguments.

TRAIL_ARG:

Pass the length of a CHARACTER argument to a Fortran routine.

WORD:

Declare a WORD argument.

WORD_ARRAY:

Declare a WORD array argument.

Generate pointers to arguments —

GENPTR_BYTE:

Generate a pointer to a BYTE argument.

GENPTR_BYTE_ARRAY:

Generate a pointer to a BYTE array argument.

GENPTR_CHARACTER:

Generate a pointer to a CHARACTER argument.

GENPTR_CHARACTER_ARRAY:

Generate a pointer to a CHARACTER array argument.

GENPTR_DOUBLE:

Generate a pointer to a DOUBLE PRECISION argument.

GENPTR_DOUBLE_ARRAY:

Generate a pointer to a DOUBLE PRECISION array argument.

GENPTR_INTEGER:

Generate a pointer to an INTEGER argument.

GENPTR_INTEGER_ARRAY:

Generate a pointer to an INTEGER array argument.

GENPTR_LOGICAL:

Generate a pointer to a LOGICAL argument.

GENPTR_LOGICAL_ARRAY:

Generate a pointer to a LOGICAL array argument.

GENPTR_POINTER:

Generate a pointer to a POINTER argument.

GENPTR_REAL:

Generate a pointer to a REAL argument.

GENPTR_REAL_ARRAY:

Generate a pointer to a REAL array argument.

GENPTR_WORD:

Generate a pointer to a WORD argument.

GENPTR_WORD_ARRAY:

Generate a pointer to a WORD array argument.

Data types —

F77_BYTE_TYPE:

Define the type BYTE.

F77_CHARACTER_TYPE:

Define the type CHARACTER.

F77_DOUBLE_TYPE:

Define the type DOUBLE PRECISION.

F77_INTEGER_TYPE:

Define the type INTEGER.

F77_LOGICAL_TYPE:

Define the type LOGICAL.

F77_REAL_TYPE:

Define the type REAL.

F77_WORD_TYPE:

Define the type WORD.

Logical values —

F77_FALSE:

The logical value FALSE.

F77_ISFALSE:

Is this the Fortran logical value false?

F77_ISTRUE:

Is this the Fortran logical value true?

F77_TRUE:

The logical value TRUE.

External names —

F77_EXTERNAL_NAME:

The external name of a function.

Common blocks —

F77_BLANK_COMMON:

Refer to blank common.

F77_NAMED_COMMON:

Refer to a named common block.

Declaring variables for passing to a Fortran routine —

DECLARE_BYTE:

Declare a BYTE variable.

DECLARE_BYTE_ARRAY:

Declare a BYTE array.

DECLARE_CHARACTER:

Declare a CHARACTER variable.

DECLARE_CHARACTER_ARRAY:

Declare a CHARACTER array.

DECLARE_DOUBLE:

Declare a DOUBLE variable.

DECLARE_DOUBLE_ARRAY:

Declare a DOUBLE array.

DECLARE_INTEGER:

Declare an INTEGER variable.

DECLARE_INTEGER_ARRAY:

Declare an INTEGER array.

DECLARE_LOGICAL:

Declare a LOGICAL variable.

DECLARE_LOGICAL_ARRAY:

Declare a LOGICAL array.

DECLARE_REAL:

Declare a REAL variable.

DECLARE_REAL_ARRAY:

Declare a REAL array.

DECLARE_WORD:

Declare a WORD variable.

DECLARE_WORD_ARRAY:

Declare a WORD array.

Passing arguments to a Fortran routine —

BYTE_ARG:

Pass a BYTE argument to a Fortran routine.

BYTE_ARRAY_ARG:

Pass a BYTE array argument to a Fortran routine.

CHARACTER_ARG:

Pass a CHARACTER argument to a Fortran routine.

CHARACTER_ARRAY_ARG:

Pass a CHARACTER array argument to a Fortran routine.

DOUBLE_ARG:

Pass a DOUBLE argument to a Fortran routine.

DOUBLE_ARRAY_ARG:

Pass an actual DOUBLE array argument to a Fortran routine.

F77_CALL:

Call a Fortran routine from C.

INTEGER_ARG:

Pass an INTEGER argument to a Fortran routine.

INTEGER_ARRAY_ARG:

Pass an INTEGER array argument to a Fortran routine.

LOGICAL_ARG:

Pass a LOGICAL argument to a Fortran routine.

LOGICAL_ARRAY_ARG:

Pass a LOGICAL array argument to a Fortran routine.

REAL_ARG:

Pass a REAL argument to a Fortran routine.

REAL_ARRAY_ARG:

Pass a REAL array argument to a Fortran routine.

WORD_ARG:

Pass a WORD argument to a Fortran routine.

WORD_ARRAY_ARG:

Pass a WORD array argument to a Fortran routine.

21.7.3 PRIMDAT — Primitive numerical data processing

[SUN/39]

There are a great many routines in this library so only generic names are given and the various possibilities are listed in tables. Variables are specified in routine names by lower-case letters, as shown in Table 1.2.

Value functions —

VAL_fs:

Apply function f to one or two numbers of type s.

VAL_sTOt:

Convert a number from type s to type t.

Vectorised routines —

VEC_fs:

Apply function f to one or two vectors of type s.

VEC_sTOt:

Convert a vector from type s to type t.

Numerical functions —

NUM_fs:

Apply function f to one or two numbers of type s.

NUM_rs:

Apply relation r to two numbers of type s.

NUM_sTOt:

Convert a number from type s to type t.

Table 1.3: The data type codes used in constants and routine names, and the HDS and VAX Fortran types to which they correspond.

Table 1.4: The relational operation codes used in the names of NUM functions and the inter-comparisons to which they correspond.

Table 1.5: Function codes used in routine names and the operations to which they correspond. The functions shown here are implemented for all the numerical data types (type codes UB, B, UW, W, I, R & D).

Table 1.6: Function codes used in routine names and the operations to which they correspond. The functions shown here are only implemented for the floating point data types (type codes R & D).

21.7.4 PSX — Posix interface

[SUN/121] Process environment: 

Pseudo-Random Numbers —

PSX_RAND:

Generate a random number.

PSX_SRAND:

Set the seed for the random number generator.

Memory Management —

PSX_CALLOC:

Allocate space for several objects of specified type.

PSX_FREE:

Free virtual memory.

PSX_MALLOC:

Allocate virtual memory.

PSX_REALLOC:

Change the size of an allocated region of virtual memory.

Date and Time —

PSX_ASCTIME:

Convert a time structure to a character string.

PSX_CTIME:

Convert the calendar time to a character string

PSX_LOCALTIME:

Convert the value returned by PSX_TIME to individual values.

PSX_TIME:

Get the current calendar time.

21.7.5 SLALIB — Positional astronomy and time

[SUN/67]

Some of the items listed below are implemented as subroutines and some as functions. Also, some items are implemented in both single-precision and double-precision forms. For brevity, only the single-precision forms are listed.

String decoding —

SLA_INTIN:

Convert free-format string into integer.

SLA_FLOTIN:

Convert free-format string into floating-point number.

SLA_AFIN:

Convert free-format string from deg,arcmin,arcsec to radians.

Sexagesimal conversion —

SLA_CTF2D:

Hours, minutes, seconds to days.

SLA_CD2TF:

Days to hours, minutes, seconds.

SLA_CTF2R:

Hours, minutes, seconds to radians.

SLA_CR2TF:

Radians to hours, minutes, seconds.

SLA_CAF2R:

Degrees, arcminutes, arcseconds to radians.

SLA_CR2AF:

Radians to degrees, arcminutes, arcseconds.

Angles, Vectors and Rotation matrices —

SLA_RANGE:

Normalise angle into range $\pm \pi$.

SLA_RANORM:

Normalise angle into range $0-2\pi$.

SLA_CS2C:

Spherical coordinates to $\left[x,y,z\right]$.

SLA_CC2S:

$\left[x,y,z\right]$ to spherical coordinates.

SLA_VDV:

Scalar product of two 3-vectors.

SLA_VXV:

Vector product of two 3-vectors.

SLA_VN:

Normalise a 3-vector also giving the modulus.

SLA_SEP:

Angle between two points on a sphere.

SLA_BEAR:

Direction of one point on a sphere seen from another.

SLA_EULER:

Form rotation matrix from three Euler angles.

SLA_AV2M:

Form rotation matrix from axial vector.

SLA_M2AV:

Determine axial vector from rotation matrix.

SLA_MXV:

Rotate vector forwards.

SLA_IMXV:

Rotate vector backwards.

SLA_MXM:

Product of two 3x3 matrices.

SLA_CS2C6:

Convert position and velocity in spherical coordinates to Cartesian coordinates.

SLA_CC62S:

Convert position and velocity in Cartesian coordinates to spherical coordinates.

Calendars —

SLA_CLDJ:

Gregorian Calendar to Modified Julian Date.

SLA_CALDJ:

Gregorian Calendar to Modified Julian Date, permitting century default.

SLA_DJCAL:

Modified Julian Date to Gregorian Calendar, convenient for formatted output.

SLA_DJCL:

Modified Julian Date to Gregorian Year, Month, Day, Fraction.

SLA_CALYD:

Calendar to year and day in year.

SLA_EPB:

Modified Julian Date to Besselian Epoch.

SLA_EPB2D:

Besselian Epoch to Modified Julian Date.

SLA_EPJ:

Modified Julian Date to Julian Epoch.

SLA_EPJ2D:

Julian Epoch to Modified Julian Date.

Timescales —

SLA_GMST:

Conversion from Universal Time to sidereal time.

SLA_EQEQX:

Equation of the equinoxes.

SLA_DAT:

Offset of Atomic Time from UT: TAI$-$UTC.

SLA_DTT:

Offset of “Ephemeris Time” from UT: TDT$-$UTC.

SLA_RCC:

Relativistic clock correction: TDB$-$TDT.

Precession and Nutation —

SLA_NUT:

Nutation matrix.

SLA_NUTC:

Longitude and obliquity components of nutation, and mean obliquity.

SLA_PREC:

Precession matrix.

SLA_PRENUT:

Combined precession/nutation matrix.

SLA_PREBN:

Precession matrix, old system.

SLA_PRECES:

Precession, in either the old or the new system.

Proper motion —

SLA_PM:

Adjust for proper motion.

FK4/5 conversions —

SLA_FK425:

Convert B1950.0 FK4 star data to J2000.0 FK5.

SLA_FK45Z:

Convert B1950.0 FK4 position to J2000.0 FK5 assuming zero proper motion in an inertial frame and no parallax.

SLA_FK524:

Convert J2000.0 FK5 star data to B1950.0 FK4.

SLA_FK54Z:

Convert J2000.0 FK5 position to B1950.0 FK4 assuming zero proper motion and no parallax.

SLA_DBJIN:

Like SLA_DFLTIN but with extensions to accept leading ‘B’ and ‘J’.

SLA_KBJ:

Select epoch prefix ‘B’ or ‘J’.

SLA_EPCO:

Convert an epoch into the appropriate form – ‘B’ or ‘J’.

Elliptic aberration —

SLA_ETRMS:

E-terms.

SLA_SUBET:

Remove the E-terms.

SLA_ADDET:

Add the E-terms.

Geocentric coordinates —

SLA_OBS:

Interrogate list of observatory parameters.

SLA_GEOC:

Convert geodetic position to geocentric.

SLA_PVOBS:

Position and velocity of observatory.

Apparent and observed place —

SLA_MAP:

Mean place to geocentric apparent place.

SLA_MAPPA:

Precompute mean to apparent parameters.

SLA_MAPQK:

Mean to apparent using precomputed parameters.

SLA_MAPQKZ:

Mean to apparent using precomputed parameters, for zero proper motion, parallax and radial velocity.

SLA_AMP:

Geocentric apparent place to mean place.

SLA_AMPQK:

Apparent to mean using precomputed parameters.

SLA_AOP:

Apparent place to observed place.

SLA_AOPPA:

Precompute apparent to observed parameters.

SLA_AOPPAT:

Update sidereal time in apparent to observed parameters.

SLA_AOPQK:

Apparent to observed using precomputed parameters.

SLA_OAP:

Observed to apparent.

SLA_OAPQK:

Observed to apparent using precomputed parameters.

SLA_ZD:

$\left[h,\delta \right]$ to zenith distance.

SLA_PA:

$\left[h,\delta \right]$ to parallactic angle.

Refraction and air mass —

SLA_REFRO:

Change in zenith distance due to refraction.

SLA_REFCO:

Constants for simple refraction model.

SLA_REFZ:

Unrefracted to refracted ZD, simple model.

SLA_REFV:

Unrefracted to refracted $\left[Az,El\right]$ vector, simple model.

SLA_AIRMAS:

Air mass.

Ecliptic coordinates —

SLA_ECMAT:

Equatorial to ecliptic rotation matrix.

SLA_EQECL:

J2000.0 ‘FK5’ to ecliptic coordinates.

SLA_ECLEQ:

Ecliptic coordinates to J2000.0 ‘FK5’.

Galactic coordinates —

SLA_EG50:

B1950.0 ‘FK4’ to galactic.

SLA_GE50:

Galactic to B1950.0 ‘FK4’.

SLA_EQGAL:

J2000.0 ‘FK5’ to galactic.

SLA_GALEQ:

Galactic to J2000.0 ‘FK5’.

Supergalactic coordinates —

SLA_GALSUP:

Galactic to supergalactic.

SLA_SUPGAL:

Supergalactic to galactic.

Ephemerides —

SLA_EARTH:

Approximate heliocentric position and velocity of the Earth.

SLA_EVP:

Barycentric and heliocentric velocity and position of the Earth.

SLA_MOON:

Approximate geocentric position and velocity of the Moon.

SLA_RVEROT:

Velocity component due to rotation of the Earth.

SLA_ECOR:

Components of velocity and light time due to Earth orbital motion.

SLA_RVLSR:

Velocity component due to solar motion wrt LSR.

SLA_RVGALC:

Velocity component due to rotation of the Galaxy.

SLA_RVLG:

Velocity component due to rotation and translation of the Galaxy, relative to the mean motion of the local group.

Astrometry —

SLA_S2TP:

Transform spherical coordinates into tangent plane.

SLA_TP2S:

Transform tangent plane coordinates into spherical.

SLA_PCD:

Apply pincushion/barrel distortion.

SLA_UNPCD:

Remove pincushion/barrel distortion.

SLA_FITXY:

Fit a linear model to relate two sets of $\left[x,y\right]$ coordinates.

SLA_PXY:

Compute predicted coordinates and residuals.

SLA_INVF:

Invert a linear model.

SLA_XY2XY:

Transform one $\left[x,y\right]$.

SLA_DCMPF:

Decompose a linear fit into scales etc.

Numerical methods —

SLA_SMAT:

Matrix inversion and solution of simultaneous equations.

SLA_SVD:

Singular value decomposition of a matrix.

SLA_SVDSOL:

Solution from given vector plus SVD.

SLA_SVDCOV:

Covariance matrix from SVD.

SLA_RANDOM:

Generate pseudo-random real number in the range $0\le x<1$.

SLA_GRESID:

Generate pseudo-random normal deviate ($\equiv$ ‘Gaussian residual’).

Real-time —

SLA_WAIT:

Interval wait.

21.7.6 TRANSFORM — Coordinate transformation

[SUN/61]