14

SUN/114.4

Starlink Project
Starlink User Note 114.4

Malcolm J. Currie
Alan J. Chipperfield

1999 September 24


PAR
Interface to the ADAM Parameter System

Version 2.3

Programmer’s Manual



Abstract

PAR is a library of Fortran subroutines that provides convenient mechanisms for applications to exchange information with the outside world, through input-output channels called parameters. Parameters enable a user to control an application’s behaviour. PAR supports numeric, character, and logical parameters, and is currently implemented only on top of the ADAM parameter system.

The PAR library permits parameter values to be obtained, without or with a variety of constraints. Results may be put into parameters to be passed onto other applications. Other facilities include setting a prompt string, and suggested defaults.

This document also introduces a preliminary C interface for the PAR library – this may be subject to change in the light of experience.

Contents

1 Introduction
2 What is a Parameter?
3 Parameter States
4 Error Handling
5 Basic Routines
 5.1 Getting a Parameter’s Value
 5.2 Getting an Array of Values
 5.3 Putting a Parameter’s Value
 5.4 Cancelling a Parameter
 5.5 Setting the Dynamic Prompt
 5.6 Setting the Dynamic Default
 5.7 Setting Lower and Upper Limits
 5.8 Cancelling Dynamic Values
  5.8.1 Range
  5.8.2 Dynamic Defaults
 5.9 Inquiring the State of a Parameter
6 Abort and Null
 6.1 Abort
 6.2 Null
7 Extended Routines
 7.1 Scalar Values between Limits
 7.2 Arrays of Values between Limits
 7.3 Parity Constraint
 7.4 Menu Constraint
 7.5 Combined Constraints
 7.6 Logical Value
8 Other Types of Parameters
9 Compilation and Linking
 9.1 UNIX
 9.2 VMS
10 Acknowledgements
A Alphabetical List of Routines
B Classified List of Routines
 B.1 Getting Values from a Parameter without Constraints
 B.2 Getting Parameter Values from a Menu
 B.3 Getting Values within Ranges
 B.4 Putting Values into Parameters
 B.5 Miscellaneous
 B.6 Inquiry Routines
C Error Codes
D Correspondence between PAR and SUBPAR States
E The C Interface
F The C Interface Function Prototypes
G Reference Manual
PAR_CANCL – Cancels a parameter
PAR_CHOIC – Obtains from a parameter a character value selected from a menu of options
PAR_CHOIV – Obtains from a parameter a list of character values selected from a menu of options
PAR_DEF0x – Sets a scalar dynamic default parameter value
PAR_DEF1x – Sets a vector of values as the dynamic default for a parameter
PAR_DEFNx – Sets an array of values as the dynamic default for a parameter
PAR_EXACx – Obtains an exact number of values from a parameter
PAR_GDR0x – Obtains a scalar value within a given range from a parameter
PAR_GDR1x – Obtains an exact number of values within a given range from a parameter
PAR_GDRVx – Obtains a vector of values within a given range from a parameter
PAR_GET0x – Obtains a scalar value from a parameter
PAR_GET1x – Obtains a vector of values from a parameter
PAR_GETNx – Obtains an array parameter value
PAR_GETVx – Obtains a vector of values from a parameter regardless of the its shape
PAR_GEVEN – Obtains an even integer value from a parameter
PAR_GODD – Obtains an odd integer value from a parameter
PAR_GRM1x – Obtains from a parameter an exact number of values each within a given range
PAR_GRMVx – Obtains from a parameter a vector of values each within a given range
PAR_GTD0L – Obtains a logical value from a parameter with a dynamic default
PAR_MAXx – Sets a maximum value for a parameter
PAR_MINx – Sets a minimum value for a parameter
PAR_MIX0x – Obtains from a parameter a character value from either a menu of options or within a numeric range
PAR_MIXVx – Obtains from a parameter character values from either a menu of options or within a numeric range
PAR_PROMT – Sets a new prompt string for a parameter
PAR_PUT0x – Puts a scalar value into a parameter
PAR_PUT1x – Puts a vector of values into a parameter
PAR_PUTNx – Puts an array of values into a parameter
PAR_PUTVx – Puts an array of values into a parameter as if the parameter were a vector
PAR_STATE – Inquires the state of a parameter
PAR_UNSET – Cancels various parameter control values.