Postscript Operators 'd'

def key value def
- associates key with value in the current dictionary-the one on the top of the dictionary stack . If key is already present in the current dictionary, def simply replaces its value. Otherwise, def creates a new entry for key and stores value with it.

If the current dictionary is in global VM and value is a composite object whose value is in local VM, an invalidaccess error occurs .

EXAMPLE:
/ncnt 1 def % Define ncnt to be 1 in current
dict
/ncnt ncnt 1 add def % ncnt now has value 2

ERRORS: dictfull, invalidaccess,

limitcheck, stackunderflow,

typecheck, VMerror

SEE ALSO: store, put

Troubleshooting index Back to Postscript index

defaultmatrix matrix defaultmatrix matrix

replaces the value of matrix with the default transformation matrix for the current output device and pushes this modified matrix back on the operand stack.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: currentmatrix, initmatrix,

setmatrix

Troubleshooting index Postscript Index

definefont key font definefont font

registers font as a font dictionary associated with key (usually a name). definefont first checks that font is a well-formed font dictionary-in other words, contains all required key-value pairs. It inserts an additional entry whose key is FID and whose value is an object of type fontID. The dictionary must be large enough to accommodate this additional entry. It makes the dictionary's access read-only. Finally, it associates key with font in the font directory.

In Level 2, it is permissible to associate a font dictionary with more than one key. If font has already been registered, definefont does not alter it in any way.

If font is a composite font , definefont also inserts the entries MIDVector and CurMID, and adds entries PrefEnc, EscChar, ShiftIn, and ShiftOut if they are required and are not already present. All the descendant fonts must have been registered by definefont previously.

Subsequent invocation of findfont with key will return font. Font registration is subject to the normal semantics of VM . In particular, the lifetime of the definition depends on the VM allocation mode at the time definefont is executed. A local definition can be undone by a subsequent restore.

definefont is actually a special case of defineresource operating on the Font category.

ERRORS: limitcheck, rangecheck,

dictfull, invalidfont,

stackunderflow, typecheck,

invalidaccess

SEE ALSO: makefont, scalefont,

setfont, defineresource,

FontDirectory, GlobalFontDirectory,

setglobal

Troubleshooting index Back to Postscript index

defineresource key instance category defineresource instance LEVEL 2

associates a resource instance with a resource name in a specified category. category is a name object that identifies a resource category, such as Font . key is a name or string object that will be used to identify the resource instance. (Names and strings are interchangeable; other types of keys are permitted but are not recommended.) instance is the resource instance itself; its type must be appropriate to the resource category.

Before defining the resource instance, defineresource verifies that the instance object is the correct type. Depending on the resource category, it may also perform additional validation of the object and may have other side effects. Finally, it makes the object read-only if its access is not already restricted.

The lifetime of the definition depends on the VM allocation mode in effect at the time defineresource is executed. If local VM allocation is in effect ( currentglobal returns false), the effect of defineresource is undone by the next nonnested restore. If global VM allocation is in effect ( currentglobal returns true), the effect of defineresource persists until global VM is restored at the end of the job. If the current job is not encapsulated, the effect of a global defineresource persists indefinitely, and may be visible to other execution contexts.

Local and global definitions are maintained separately. If a new resource instance is defined with the same category and key as an existing one, the new definition overrides the old one. The precise effect depends on whether the old definition is local or global and whether the new definition (current VM allocation mode) is local or global. There are two main cases:

New definition is local-defineresource installs the new local definition, replacing an existing local definition if there is one. If there is an existing global definition, defineresource does not disturb it. However, the global definition is obscured by the local one. If the local definition is later removed, the global definition reappears.
New definition is global-defineresource first removes an existing local definition if there is one. It then installs the new global definition, replacing an existing global definition if there is one.

It is permissible to use defineresource multiple times to associate a given resource instance with more than one key.

If the category name is unknown, an undefined error occurs. If the instance is of the wrong type for the specified category, a typecheck error occurs. If the instance is in local VM but the current VM allocation mode is global, an invalidaccess error occurs. This is analogous to storing a local object into a global dictionary. Other errors can occur for specific categories. For example, when dealing with the Font category, defineresource can execute an invalidfont error.

ERRORS: invalidaccess, stackunderflow,

typecheck, undefined

SEE ALSO: undefineresource, findresource,

resourcestatus, resourceforall

Troubleshooting index Back to Postscript index

defineusername index name defineusername - DPS

establishes an association between the non-negative integer index and the name object name in the user name table. Subsequently, the scanner will substitute name when it encounters any binary encoded name token or object that refers to the specified user name index. Because binary encoded names specify their own literal or executable attributes, it does not matter whether name is literal or executable.

The user name table is an adjunct to the current context's local VM. The effect of adding an entry to the table is immediately visible to all contexts that share the same local VM. Additions to the table are not affected by save and restore. The association between index and name persists for the remaining lifetime of the local VM.

The specified index must previously be unused in the name table or must already be associated with the same name. Changing an existing association is not permitted (an invalidaccess error will occur). There may be an implementation limit on index values. Assigning index values sequentially starting at zero is strongly recommended.

ERRORS: invalidaccess, limitcheck,

rangecheck, stackunderflow,

typecheck

Troubleshooting index Back to Postscript index

defineuserobject index any defineuserobject - LEVEL 2

establishes an association between the non-negative integer index and the object any in the UserObjects array. First, it creates a UserObjects array in userdict if one is not already present. It extends an existing UserObjects array if necessary. It then executes the equivalent of

userdict /UserObjects get
3 1 roll put

In other words, it simply stores any into the array at the position specified by index.

If defineuserobject creates or extends the UserObjects array, it allocates the array in local VM, regardless of the current VM allocation mode.

The behavior of defineuserobject obeys normal PostScript language semantics in all respects. In particular, the modification to the UserObjects array and to userdict, if any, is immediately visible to all contexts that share the same local VM. It can be undone by a subsequent restore according to the usual VM rules. index values must be within the range permitted for arrays; a large index value may cause allocation of an array that would exhaust VM resources. Assigning index values sequentially starting at zero is strongly recommended.

ERRORS: limitcheck, rangecheck,

stackunderflow, typecheck,

UserObjects

Troubleshooting index Back to Postscript index

deletefile filename deletefile - LEVEL 2

removes the specified file from its storage device. If no such file exists, an undefinedfilename error occurs. If the device does not allow this operation, an invalidfileaccess error occurs. If an environment dependent error is detected, an ioerror occurs.

ERRORS: invalidfileaccess, ioerror,

stackunderflow, typecheck , undefinedfilename

SEE ALSO: file, renamefile,

status

Troubleshooting index Back to Postscript index

detach context detach - DPS

specifies that the execution context identified by the integer context is to terminate immediately when it finishes executing its top-level procedure, whereas ordinarily it would wait for a join. If the context is already waiting for a join, detach causes it to terminate immediately.

detach executes an invalidcontext error if context is not a valid context identifier or if the context has already been joined or detached. It is permissible for context to identify the current context.

ERRORS: invalidcontext, stackunderflow,

typecheck

SEE ALSO: currentcontext, fork,

join

Troubleshooting index Back to Postscript index

deviceinfo - deviceinfo dict DPS

returns a read-only dictionary containing static information about the current device. The composition of this dictionary varies according to the properties of the device. The information in the dictionary may not be meaningful for a page-oriented or other non-display device.

The use of deviceinfo after a setcachedevice operation within the scope of a BuildChar procedure is not permitted. An undefined error results.

ERRORS: stackoverflow, undefined

Troubleshooting index Back to Postscript index

dict int dict dict

creates an empty dictionary with an initial capacity of int elements and pushes the created dictionary object on the operand stack. int is expected to be a nonnegative integer. The dictionary is allocated in local or global VM according to the VM allocation mode.

In Level 1 implementations, the resulting dictionary has a maximum capacity of int elements. Attempting to exceed that limit causes a dictfull error.

In Level 2 implementations, the int operand specifies only the initial capacity; the dictionary can grow beyond that capacity if necessary. The dict operator immediately consumes sufficient VM to hold int key-value pairs. If more than that number of entries are subsequently stored in the dictionary, additional VM is consumed at that time.

There is a cost associated with expanding a dictionary beyond its initial allocation. For efficiency reasons, a dictionary is expanded in chunks rather than one element at a time, so it may contain a substantial amount of unused space. If a program knows how large a dictionary it needs, it should create one of that size initially. On the other hand, if a program cannot predict how large the dictionary will eventually grow, it should choose a small initial allocation sufficient for its immediate needs. The built-in writable dictionaries (for example, userdict) follow the latter convention.

ERRORS: limitcheck, stackunderflow,

typecheck, VMerror

SEE ALSO: begin, end,

length, maxlength

Troubleshooting index Back to Postscript index

dictfull (error)

occurs when def, put, or store attempts to define a new entry in a dictionary that is already full-in other words, whose length and maxlength are already equal. This can occur only in Level 1 implementations, where a dictionary has a fixed limit on the number of entries with distinct keys it can hold. This limit is established by the operand to the dict operator that creates the dictionary.

SEE ALSO: def, put, store,

dict

Troubleshooting index Postscript Index

dictstack array dictstack subarray

stores all elements of the dictionary stack into array and returns an object describing the initial n-element subarray of array, where n is the current depth of the dictionary stack. dictstack copies the topmost dictionary into element n-1 of array and the bottommost one into element 0 of array. The dictionary stack itself is unchanged. If the length of array is less than the depth of the dictionary stack, dictstack executes a rangecheck error.

ERRORS: invalidaccess, rangecheck, , stackunderflow, typecheck

SEE ALSO: countdictstack

Troubleshooting index Back to Postscript index

dictstackoverflow (error)

The dictionary stack has grown too large. Too many begin operators without corresponding end operators have pushed too many dictionaries on the dictionary stack.

Before invoking this error, the interpreter creates an array containing all elements of the dictionary stack stored as if by dictstack, pushes this array on the operand stack, and resets the dictionary stack to contain only the permanent entries.

SEE ALSO: begin, countdictstack,

cleardictstack

Troubleshooting index Back to Postscript index

dictstackunderflow (error)

An attempt has been made to remove (end) the bottommost instance of userdict from the dictionary stack. This occurs if an end is executed for which there was no corresponding begin.

SEE ALSO: end

Troubleshooting index Back to Postscript index

div num1 num2 div quotient

divides num1 by num2, producing a result that is always a real even if both operands are integers. Use idiv if an integer result is desired.

EXAMPLE:
3 2 div -> 1.5
4 2 div -> 2.0

ERRORS: stackunderflow, typecheck,

undefinedresult

SEE ALSO: idiv, add,

mul, sub, mod

Troubleshooting index Back to Postscript index

dtransform dx dy dtransform dx` dy`
dx dy matrix dtransform dx` dy`

With no matrix operand, dtransform (delta transform) transforms the distance vector (dx, dy) by the CTM to produce the corresponding distance vector (dx`, dy`) in device space. If the matrix operand is supplied, dtransform transforms the distance vector by matrix rather than by CTM.

A delta transformation is similar to a normal transformation , but the translation components (tx and ty) of the transformation matrix are not used, making the distance vectors positionless in both user space and device space. This is useful for determining how distances map from user space to device space.

ERRORS: rangecheck, stackunderflow,

typecheck

SEE ALSO: idtransform, transform,

itransform

Troubleshooting index Back to Postscript index

dup any dup any any

duplicates the top element on the operand stack. Note that dup copies only the object. The value of a composite object is not copied but is shared.

ERRORS: stackoverflow, stackunderflow

SEE ALSO: copy, index

Troubleshooting index Back to Postscript index

Original file name: PSL2d