s2c$xs (4) --- protected double-word store operation     06/25/82


            _C_a_l_l_i_n_g _I_n_f_o_r_m_a_t_i_o_n

                 logical function s2c$xs (ptr_to_variable, old_value, new_value)
                 shortcall s2c$xs (4)

                 pointer ptr_to_variable
                 untyped old_value, new_value

                 Library: shortlb
                 Also declared in =incl=/shortlb.r.i


            _F_u_n_c_t_i_o_n

                 The function implements an uninterruptable form of test-and-
                 set  operation.  The parameter 'ptr_to_variable' is a 2 word
                 virtual memory pointer to a 2 word location in memory to  be
                 tested and possibly modified.

                 If  the  variable  contains  the  same  value as provided in
                 'old_value' then the variable is updated to 'new_value'  and
                 the  function returns TRUE.  If the variable is not equal to
                 'old_value' then the function returns FALSE and no change is
                 made to the variable.  Effectively,

                             if (variable == old_value) {
                                variable = new_value
                                return (TRUE)
                                }

                             else
                                return (FALSE)


            _I_m_p_l_e_m_e_n_t_a_t_i_o_n

                 Implemented as a simple  PMA  routine  entered  via  a  JSXB
                 (shortcall).   The function uses the STLC instruction, which
                 is guaranteed to be atomic (non-interruptable).

                 Note that any routine using this call must be compiled using
                 the "-q" option of 'fc'.


            _B_u_g_s

                 The pointer supplied is not checked for validity.

                 Locally supported.


            _S_e_e _A_l_s_o

                 fc (1), s1c$xs  (4),  _S_y_s_t_e_m  _A_r_c_h_i_t_e_c_t_u_r_e  _R_e_f_e_r_e_n_c_e  _G_u_i_d_e
                 (Prime PDR 3060)



            s2c$xs (4)                    - 1 -                    s2c$xs (4)