access.c

access.c provides the user and interface programmer with an ease-to-use enviroment to read data out of the atom data structure again.

Comments

First the parameter orbital string is analyzed to get the orbital symbol and the shell number. If these are not found an error code will be returned to the calling function. After these validations a while loop looks for the orbital symbol by using the XAFirstOrbital and XANextOrbital functions. If it is found a pointer to this orbital will be returned.

shell_ptr XAShell(atom_ptr curr_atom, char *orbital_string)

works like XAOrbital, first the orbital is searched by using XAOrbital. Then the procedure looks for the shell number and, when found, returns a pointer to the shell.

orbital_value_ptr XAData(int i, atom_ptr, char *orbital_string)

XAShell is used to access the shell, which is given by the orbital string parameter. The while loop looks for the ith data element in this shell, where i=0 stands for the first data block, i=1 the second etc. If i is greater than the number of data blocks a POINTER_RETURN_ERROR is returned to the calling function.

int XADataN(int i, atom_ptr curr_atom, char *orbital_string)
float XADataC(int i, atom_ptr curr_atom, char *orbital_string)
float XADataAlpha(int i, atom_ptr curr_atom, char *orbital_string)

These functions are based on the XAData procedure, so the functionality is the same. E.g. instead of using XACurrentN(XAData(...)) we can use the abbreviation XADataN now.

int XASetNextShell(shell_ptr curr_shell, shell_ptr new_shell)

XASetNextShell sets the next_shell pointer of curr_shell to new_shell. Currently this procedure is only used to delete orbitals by calling XASetNextShell with the parameter NULL.

orbital_array_ptr XAOrbitalArray(atom_ptr curr_atom)

XAOrbitalArray returns general information of an atom to the calling procedure. The information is coded into the orbital_array_ptr structure which is defined as follows:

• int number_orbitals
  gives the number of different orbitals types which are stored in the atomic data file. For example, aluminium has two orbital types, i.e. S and P, so number_orbitals is set to two.

• char symbol[<0..number_orbitals - 1>]
  the array symbol stores the symbol for each orbital type. Please note that orbital types are stored in LIFO order in the XA internal atom structure. For example, for aluminium symbol[0] is set to P and symbol[1] to S.

• int length[<0..number_orbitals - 1>]
  the array length gives for each orbital type the amount of shells which possess an orbital with the according type. In the case of aluminium, which consists of 1S, 2S, 3S and 2P, 3P, length[0], i.e. for orbital type P, has the value 2 and length[1], i.e. for orbital type S, the value 3.

• char *pointer[<0..number_orbitals - 1>][<0..length[i] - 1>], where i = 0..number_orbitals - 1
  the array pointer contains all the names of the orbitals in the atomic data file. For example, for aluminium we get:

  pointer[0][0] = "2P"  pointer[0][1] = "3P"
  pointer[1][0] = "1S"  pointer[1][1] = "2S"  pointer[1][2] = "3S"
  

To get these values XAOrbitalArray just examines every pointer of the atom data structure recursively, creates the return structure and returns it to the calling procedure. The various orbitals and shells are accessed by the access functions and therefore based on their correctness. Additionally, every "dead end" of the atom data structure must be marked by a NULL pointer.

Please note: whereas orbital types are stored as LIFO order, shells are in FIFO order.

You can access these values in your procedure by using the following access procedures.